chiridion 0.3.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e87a90e1e1a9905e4ec8fe90fa2bb3dfbdf5c30c69d22dc40076e71ac282251
+  data.tar.gz: d5ca6cfe8f1d60040f0bc47a79a047b436f17cb6cd7ed94981cae3e4b4629396
+SHA512:
+  metadata.gz: 2280d3d512e5ac20601e33e63ccac2fed856b1e0e9cbd89ec22ca36b32b1ac944468a44b6518fbb674ea603b4c222ea9d034fb29024626d0c618bfe94b36128d
+  data.tar.gz: 67ec810bdd67b201303712dcddb97d5790b7991bf89494bedcf30bfe8d32e94f5ca449445b9526268ee3808b621faa5dda647137fbf3b86212517e02cee9c43a

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## [0.3.4] - 2026-05-18
+
+### Fixed
+- Declare `logger` and `base64` as runtime dependencies. Both are Ruby
+  default-gem extractions (`base64` @ 3.4, `logger` @ 3.5/4.0) that
+  chiridion needs at runtime — `logger` directly (engine), `base64`
+  transitively via `liquid` (which does not declare it). Without these,
+  `require "chiridion"` raised `LoadError` for any consumer running
+  under bundler on Ruby >= 3.4. No behavior change.
+
+> Note: this changelog was not maintained for 0.2.x–0.3.3; entries
+> resume here rather than reconstruct unrecorded history.
+
+## [0.1.0] - 2024-12-09
+
+### Added
+- Initial release
+- YARD-based documentation extraction
+- RBS type signature integration
+- Liquid template rendering
+- Obsidian-compatible wikilinks
+- Spec example extraction
+- Drift detection for CI/CD

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Joseph Wecker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# Chiridion
+
+Agent-oriented documentation generator for Ruby projects.
+
+**Chiridion** (from Greek χειρίδιον, "handbook" — the diminutive of χείρ "hand") generates documentation optimized for AI agents and LLMs working with Ruby codebases.
+
+## Why Agent-Oriented Documentation?
+
+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 for programmatic traversal
+- **Explicit type information** from RBS (not just prose descriptions)
+- **Cross-reference wikilinks** that can be followed programmatically
+- **Compact method signatures** that maximize information density
+
+## Features
+
+- **YARD Integration** — Extracts docstrings, @param, @return, @example tags
+- **RBS Authority** — RBS type signatures (inline or in sig/) are authoritative over YARD
+- **Inline RBS Preferred** — Supports `@rbs` inline annotations via rbs-inline
+- **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
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "chiridion", path: "~/src/chiridion"  # Local development
+```
+
+## Usage
+
+### Configuration
+
+```ruby
+Chiridion.configure do |config|
+  config.source_path = "lib/myproject"
+  config.output = "docs/sys"
+  config.namespace_filter = "MyProject::"
+  config.github_repo = "user/repo"
+  config.include_specs = true
+end
+```
+
+### Generate Documentation
+
+```ruby
+Chiridion.refresh
+```
+
+Or with explicit paths:
+
+```ruby
+engine = Chiridion::Engine.new(
+  paths: ['lib/myproject'],
+  output: 'docs/sys',
+  namespace_filter: 'MyProject::'
+)
+engine.refresh
+```
+
+### Check for Drift (CI)
+
+```ruby
+Chiridion.check  # Exits with code 1 if drift detected
+```
+
+## Inline RBS (Preferred)
+
+Chiridion prioritizes inline RBS annotations over separate sig/ files:
+
+```ruby
+class Calculator
+  # @rbs a: Integer -- first operand
+  # @rbs b: Integer -- second operand
+  # @rbs return: Integer
+  def add(a, b)
+    a + b
+  end
+end
+```
+
+This keeps types co-located with code and is the recommended approach. Separate `sig/*.rbs` files are supported as a fallback.
+
+## Output Format
+
+Generated markdown includes:
+
+```yaml
+---
+generated: 2024-12-09 10:30 UTC
+source: lib/myproject/calculator.rb:10-25
+source_url: https://github.com/user/repo/blob/main/lib/myproject/calculator.rb#L10
+type: class
+parent: Object
+---
+
+# MyProject::Calculator
+
+Calculator for basic arithmetic operations.
+
+## Methods
+
+### `#add`
+
+```rbs
+(Integer a, Integer b) -> Integer
+```
+
+Adds two integers.
+
+**Parameters:**
+- `a` (`Integer`) first operand
+- `b` (`Integer`) second operand
+
+**Returns:** `Integer`
+```
+
+## Integration with Projects
+
+### Archema
+
+```ruby
+# Gemfile
+gem "chiridion", path: "~/src/chiridion"
+
+# Configure in tasks/docs.rb
+Chiridion.configure do |config|
+  config.namespace_filter = "Archema::"
+  config.output = "docs/sys"
+end
+```
+
+### devex Integration
+
+Create a `tools/docs.rb`:
+
+```ruby
+# frozen_string_literal: true
+
+desc "Documentation generation tasks"
+
+tool "refresh" do
+  desc "Regenerate API documentation"
+
+  def run
+    require_relative "../lib/myproject"
+
+    Chiridion.configure do |c|
+      c.source_path      = "lib/myproject"
+      c.output           = "docs/sys"
+      c.namespace_filter = "MyProject::"
+      c.verbose          = verbose?  # Uses global -v flag
+    end
+    Chiridion.refresh
+  end
+end
+
+tool "check" do
+  desc "Check for documentation drift (CI mode)"
+
+  def run
+    Chiridion.check
+  end
+end
+```
+
+Then run with `dx docs refresh` or `dx docs check`.
+
+## Development
+
+Chiridion uses itself to generate its own API documentation (dogfooding). The generated docs live in `docs/sys/`.
+
+```bash
+# Run tests
+dx test
+
+# Lint
+dx lint
+
+# Regenerate Chiridion's own documentation
+dx docs refresh
+
+# Verbose output
+dx -v docs refresh
+
+# Check for drift (CI mode - exits 1 if docs are out of sync)
+dx docs check
+```
+
+This serves as both a live integration test and a reference for the output format.
+
+## Name Origin
+
+"Chiridion" is the Greek word for a small handbook or manual — appropriate for a tool that generates compact, structured documentation for AI assistants to reference.
+
+## License
+
+MIT

data/lib/chiridion/config.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Chiridion
+  # Configuration for documentation generation.
+  #
+  # Chiridion can be configured globally or per-engine instance.
+  # All options have sensible defaults for common Ruby project layouts.
+  #
+  # @example Global configuration
+  #   Chiridion.configure do |config|
+  #     config.output = 'docs/sys'
+  #     config.namespace_filter = 'MyProject::'
+  #     config.github_repo = 'user/repo'
+  #   end
+  #
+  # @example Per-project configuration file
+  #   # .chiridion.yml
+  #   output: docs/sys
+  #   namespace_filter: MyProject::
+  #   github_repo: user/repo
+  #   include_specs: true
+  #
+  class Config
+    # @return [String] Root directory of the project (defaults to current directory)
+    attr_accessor :root
+
+    # @return [String] Source directory to document (relative to root)
+    attr_accessor :source_path
+
+    # @return [String] Output directory for generated docs
+    attr_accessor :output
+
+    # @return [String, nil] Namespace prefix to filter (e.g., "MyProject::")
+    #   Only classes/modules starting with this prefix are documented.
+    #   If nil, all classes are included.
+    attr_accessor :namespace_filter
+
+    # @return [String, nil] Namespace prefix to strip from output paths
+    #   Defaults to namespace_filter value.
+    attr_writer :namespace_strip
+
+    # @return [String, nil] GitHub repository for source links (e.g., "user/repo")
+    attr_accessor :github_repo
+
+    # @return [String] Git branch for source links
+    attr_accessor :github_branch
+
+    # @return [Boolean] Whether to extract examples from spec files
+    attr_accessor :include_specs
+
+    # @return [String] Path to test directory (relative to root)
+    attr_accessor :spec_path
+
+    # @return [String] Path to RBS signatures directory (relative to root)
+    attr_accessor :rbs_path
+
+    # @return [Boolean] Verbose output during generation
+    attr_accessor :verbose
+
+    # @return [#info, #warn, #error, nil] Logger for output messages
+    attr_accessor :logger
+
+    # @return [Integer, nil] Maximum body lines for inline source display.
+    #   Methods with body <= this many lines show their implementation inline.
+    #   Set to nil or 0 to disable inline source. Default: 10.
+    attr_accessor :inline_source_threshold
+
+    # @return [Symbol] Output organization strategy (:per_class or :per_file)
+    attr_accessor :output_mode
+
+    def initialize
+      @root                    = Dir.pwd
+      @source_path             = "lib"
+      @output                  = "docs/sys"
+      @namespace_filter        = nil
+      @namespace_strip         = nil
+      @github_repo             = nil
+      @github_branch           = "main"
+      @include_specs           = false
+      @spec_path               = "test"
+      @rbs_path                = "sig"
+      @verbose                 = false
+      @logger                  = nil
+      @inline_source_threshold = 10
+      @output_mode             = :per_file
+    end
+
+    # Namespace prefix to strip from output paths.
+    # Defaults to namespace_filter if not explicitly set.
+    def namespace_strip = @namespace_strip || @namespace_filter
+
+    # Load configuration from a YAML file.
+    #
+    # @param path [String] Path to YAML configuration file
+    # @return [Config] self
+    def load_file(path)
+      return self unless File.exist?(path)
+
+      require "yaml"
+      data = YAML.safe_load_file(path, symbolize_names: true)
+      load_hash(data)
+    end
+
+    # Load configuration from a hash.
+    #
+    # @param data [Hash] Configuration values
+    # @return [Config] self
+    def load_hash(data)
+      data.each do |key, value|
+        setter = :"#{key}="
+        public_send(setter, value) if respond_to?(setter)
+      end
+      self
+    end
+
+    # @return [String] Full path to source directory
+    def full_source_path = File.join(root, source_path)
+
+    # @return [String] Full path to output directory
+    def full_output_path = File.join(root, output)
+
+    # @return [String] Full path to spec directory
+    def full_spec_path = File.join(root, spec_path)
+
+    # @return [String] Full path to RBS directory
+    def full_rbs_path = File.join(root, rbs_path)
+  end
+end

data/lib/chiridion/engine/class_linker.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Converts class/module references to Obsidian wikilinks.
+    #
+    # Handles various reference formats:
+    # - Full paths: `Autopax::Foo::Bar` → `[[foo/bar|Bar]]`
+    # - YARD curly braces: `{Extractor}` → `[[extractor|Extractor]]`
+    # - Relative names: `Writer` → `[[writer|Writer]]` (within same namespace)
+    class ClassLinker
+      # @return [Hash<String, String>] Known classes mapped to doc paths
+      attr_reader :known_classes
+
+      # @return [String, nil] Namespace prefix to strip from paths
+      attr_reader :namespace_strip
+
+      def initialize(namespace_strip: nil)
+        @namespace_strip = namespace_strip
+        @known_classes   = {}
+      end
+
+      # Register known classes from the documentation structure.
+      #
+      # @param structure [Hash] Documentation structure from Extractor
+      def register_classes(structure)
+        (structure[:classes] + structure[:modules]).each do |obj|
+          path                         = obj[:path]
+          @known_classes[path]         = doc_path(path)
+          # Also register short name for relative lookups
+          short_name                   = path.split("::").last
+          @known_classes[short_name] ||= doc_path(path)
+        end
+      end
+
+      # Convert a class path to a wikilink.
+      #
+      # @param class_path [String] Full or relative class path
+      # @param context [String, nil] Current class context for relative resolution
+      # @return [String] Wikilink like `[[path|Name]]` or original if not found
+      def link(class_path, context: nil)
+        display_name = class_path.split("::").last
+        resolved     = resolve(class_path, context: context)
+        return display_name unless resolved
+
+        "[[#{resolved}|#{display_name}]]"
+      end
+
+      # Process a docstring, converting {Class} references to wikilinks.
+      #
+      # @param text [String] Docstring text
+      # @param context [String, nil] Current class context
+      # @return [String] Text with {Class} converted to wikilinks
+      def linkify_docstring(text, context: nil)
+        return text if text.nil? || text.empty?
+
+        result = text.dup
+
+        # Convert YARD headings (= Title) to markdown headings
+        # Direct 1:1 conversion; normalize_headers filter will adjust levels for context
+        result.gsub!(/^(=+)\s+(.+)$/) do
+          level = Regexp.last_match(1).length
+          "#" * level + " " + Regexp.last_match(2)
+        end
+
+        # Convert {Class} references to wikilinks
+        result.gsub(/\{([A-Z][\w:]*)\}/) do |_match|
+          class_ref = Regexp.last_match(1)
+          link(class_ref, context: context)
+        end
+      end
+
+      # Convert a type annotation to include wikilinks where possible.
+      #
+      # Returns formatted string with backticks around non-link parts.
+      # Wikilinks must be outside backticks to render properly.
+      #
+      # @param type_str [String] Type like `Array<Autopax::Foo>` or `Hash{String => Bar}`
+      # @param context [String, nil] Current class context
+      # @return [String] Formatted type with proper backtick placement
+      def linkify_type(type_str, context: nil)
+        return "`Object`" if type_str.nil? || type_str.empty?
+
+        segments = build_type_segments(type_str, context: context)
+        format_type_segments(segments)
+      end
+
+      # Check if a class is a known documentable class.
+      #
+      # @param class_name [String] Class name to check
+      # @return [Boolean]
+      def known?(class_name) = @known_classes.key?(class_name)
+
+      SKIP_TYPES = %w[Array Hash String Integer Float Symbol Boolean Object TrueClass FalseClass NilClass Proc
+                      Class Module Numeric Enumerable Comparable void untyped nil self].freeze
+      private_constant :SKIP_TYPES
+
+      def skip_type?(class_ref) = SKIP_TYPES.include?(class_ref)
+
+      private
+
+      # Build segments from type string, identifying linkable class refs.
+      def build_type_segments(type_str, context:)
+        segments = []
+        last_end = 0
+
+        type_str.scan(/\b([A-Z]\w*(?:::[A-Z]\w*)*)\b/) do
+          class_ref   = Regexp.last_match(1)
+          match_start = Regexp.last_match.begin(0)
+          match_end   = Regexp.last_match.end(0)
+
+          segments << [:text, type_str[last_end...match_start]] if match_start > last_end
+          segments << segment_for_class(class_ref, context: context)
+          last_end = match_end
+        end
+
+        segments << [:text, type_str[last_end..]] if last_end < type_str.length
+        segments
+      end
+
+      # Create segment for a class reference (link or text).
+      def segment_for_class(class_ref, context:)
+        return [:text, class_ref] if skip_type?(class_ref)
+
+        resolved = resolve(class_ref, context: context)
+        return [:text, class_ref] unless resolved
+
+        [:link, "[[#{resolved}|#{class_ref.split('::').last}]]"]
+      end
+
+      # Format segments into final string with proper backtick placement.
+      def format_type_segments(segments)
+        return "`Object`" if segments.empty?
+        return format_pure_text(segments) unless segments.any? { |type, _| type == :link }
+        return segments.first.last if pure_link?(segments)
+
+        format_mixed_segments(segments)
+      end
+
+      def format_pure_text(segments) = "`#{segments.map(&:last).join}`"
+
+      def pure_link?(segments) = segments.size == 1 && segments.first.first == :link
+
+      # Format mixed content: wrap text in backticks, leave links bare.
+      def format_mixed_segments(segments)
+        result      = []
+        text_buffer = +""
+
+        segments.each do |type, content|
+          if type == :text
+            text_buffer << content
+          else
+            result << "`#{text_buffer}`" unless text_buffer.empty?
+            text_buffer.clear
+            result << content
+          end
+        end
+
+        result << "`#{text_buffer}`" unless text_buffer.empty?
+        result.join
+      end
+
+      # Resolve a class reference to its documentation path.
+      def resolve(class_ref, context: nil)
+        # Try exact match first
+        return @known_classes[class_ref] if @known_classes[class_ref]
+
+        # Try with namespace prefix
+        if @namespace_strip
+          full_path = "#{@namespace_strip}#{class_ref}"
+          return @known_classes[full_path] if @known_classes[full_path]
+        end
+
+        # Try relative to context
+        if context
+          relative_path = "#{context}::#{class_ref}"
+          return @known_classes[relative_path] if @known_classes[relative_path]
+
+          # Try parent namespace
+          parent       = context.split("::")[0..-2].join("::")
+          sibling_path = "#{parent}::#{class_ref}"
+          return @known_classes[sibling_path] if @known_classes[sibling_path]
+        end
+
+        nil
+      end
+
+      # Convert class path to documentation file path.
+      def doc_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) }
+        kebab_parts.join("/")
+      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