chiridion 0.3.4

data/lib/chiridion/engine/semantic_renderer.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Chiridion
+  class Engine
+    # Simplified semantic renderer that outputs structured data.
+    #
+    # Rather than formatting for human reading, this outputs all extracted
+    # semantic data as JSON (or simple markdown with JSON payload). This helps:
+    #
+    # 1. Verify what data is being captured vs. missed
+    # 2. Debug the extraction pipeline
+    # 3. Provide machine-readable documentation for LLMs/agents
+    # 4. Separate concerns: extraction vs. presentation
+    #
+    # Output format: YAML frontmatter + JSON code fence with all data.
+    class SemanticRenderer
+      def initialize(namespace_strip: nil, project_title: "API Documentation")
+        @namespace_strip = namespace_strip
+        @project_title   = project_title
+      end
+
+      # Render complete project documentation.
+      #
+      # @param project [ProjectDoc] Complete documentation from SemanticExtractor
+      # @return [Hash{String => String}] filename -> content mapping
+      def render(project)
+        files = {}
+
+        # Index
+        files["index.md"] = render_index(project)
+
+        # Type aliases are embedded where used (in each namespace's referenced_types)
+        # No separate types.md needed.
+
+        # Each namespace
+        project.namespaces.each do |ns|
+          filename        = namespace_to_filename(ns.path)
+          files[filename] = render_namespace(ns)
+        end
+
+        files
+      end
+
+      # Render index page.
+      def render_index(project)
+        frontmatter = {
+          "generated"    => project.generated_at.iso8601,
+          "title"        => @project_title,
+          "type"         => "index",
+          "description"  => project.description || "Auto-generated API documentation",
+          "class_count"  => project.classes.size,
+          "module_count" => project.modules.size
+        }
+
+        classes = project.classes.map { |c| { path: c.path, file: c.file } }
+        modules = project.modules.map { |m| { path: m.path, file: m.file } }
+
+        body_data = {
+          classes: classes,
+          modules: modules
+        }
+
+        render_document(frontmatter, body_data)
+      end
+
+      # Render type aliases reference.
+      def render_type_aliases(project)
+        frontmatter = {
+          "generated"   => project.generated_at.iso8601,
+          "title"       => "Type Aliases Reference",
+          "type"        => "reference",
+          "description" => "RBS type aliases defined across the codebase"
+        }
+
+        # Convert DocumentModel structs to hashes for JSON
+        aliases_by_namespace = project.type_aliases.transform_values do |types|
+          types.map { |t| type_alias_to_hash(t) }
+        end
+
+        body_data = { type_aliases: aliases_by_namespace }
+
+        render_document(frontmatter, body_data)
+      end
+
+      # Render a namespace (class or module).
+      def render_namespace(ns)
+        frontmatter = build_frontmatter(ns)
+        body_data   = build_body_data(ns)
+
+        render_document(frontmatter, body_data)
+      end
+
+      private
+
+      def build_frontmatter(ns)
+        fm = {
+          "generated"   => Time.now.utc.iso8601,
+          "title"       => ns.path,
+          "type"        => ns.type.to_s,
+          "description" => ns.docstring.to_s.lines.first&.strip || "",
+          "source"      => ns.file ? "#{ns.file}:#{ns.line}" : nil,
+          "tags"        => build_tags(ns)
+        }
+
+        fm["inherits"]   = ns.superclass if ns.superclass
+        fm["api"]        = ns.api if ns.api
+        fm["deprecated"] = ns.deprecated if ns.deprecated
+        fm["abstract"]   = true if ns.abstract
+        fm["since"]      = ns.since if ns.since
+
+        fm.compact
+      end
+
+      def build_tags(ns)
+        tags = [ns.type.to_s]
+        tags << "abstract" if ns.abstract
+        tags << "deprecated" if ns.deprecated
+        tags << ns.api if ns.api
+        tags.compact
+      end
+
+      def build_body_data(ns)
+        {
+          identity:        {
+            name:       ns.name,
+            path:       ns.path,
+            type:       ns.type,
+            superclass: ns.superclass,
+            file:       ns.file,
+            line:       ns.line,
+            end_line:   ns.end_line,
+            rbs_file:   ns.rbs_file
+          },
+
+          documentation:   {
+            docstring:  ns.docstring,
+            examples:   ns.examples.map { |e| example_to_hash(e) },
+            notes:      ns.notes,
+            see_also:   ns.see_also.map { |s| see_to_hash(s) },
+            deprecated: ns.deprecated,
+            abstract:   ns.abstract,
+            since:      ns.since,
+            todo:       ns.todo,
+            api:        ns.api
+          },
+
+          relationships:   {
+            includes:         ns.includes,
+            extends:          ns.extends,
+            referenced_types: ns.referenced_types.map { |t| type_alias_to_hash(t) }
+          },
+
+          members:         {
+            constants:    ns.constants.map { |c| constant_to_hash(c) },
+            type_aliases: ns.type_aliases.map { |t| type_alias_to_hash(t) },
+            ivars:        ns.ivars.map { |i| ivar_to_hash(i) },
+            attributes:   ns.attributes.map { |a| attribute_to_hash(a) },
+            methods:      ns.methods.map { |m| method_to_hash(m) }
+          },
+
+          private_methods: ns.private_methods.map { |m| method_summary(m) }
+        }
+      end
+
+      # Convert DocumentModel structs to plain hashes for JSON serialization.
+
+      def example_to_hash(e) = { name: e.name, code: e.code }
+
+      def see_to_hash(s) = { target: s.target, text: s.text }
+
+      def type_alias_to_hash(t)
+        {
+          name:        t.name,
+          definition:  t.definition,
+          description: t.description,
+          namespace:   t.namespace
+        }
+      end
+
+      def constant_to_hash(c)
+        {
+          name:        c.name,
+          value:       c.value,
+          type:        c.type,
+          description: c.description
+        }
+      end
+
+      def ivar_to_hash(i)
+        {
+          name:        i.name,
+          type:        i.type,
+          description: i.description
+        }
+      end
+
+      def attribute_to_hash(a)
+        {
+          name:        a.name,
+          type:        a.type,
+          description: a.description,
+          mode:        a.mode
+        }
+      end
+
+      def param_to_hash(p)
+        {
+          name:        p.name,
+          type:        p.type,
+          description: p.description,
+          default:     p.default,
+          prefix:      p.prefix
+        }
+      end
+
+      def option_to_hash(o)
+        {
+          param_name:  o.param_name,
+          key:         o.key,
+          type:        o.type,
+          description: o.description
+        }
+      end
+
+      def return_to_hash(r)
+        return nil unless r
+
+        { type: r.type, description: r.description }
+      end
+
+      def yield_to_hash(y)
+        return nil unless y
+
+        {
+          description: y.description,
+          params:      y.params.map { |p| param_to_hash(p) },
+          return_type: y.return_type,
+          return_desc: y.return_desc,
+          block_type:  y.block_type
+        }
+      end
+
+      def raise_to_hash(r) = { type: r.type, description: r.description }
+
+      def overload_to_hash(o) = { signature: o.signature, description: o.description }
+
+      def method_to_hash(m)
+        {
+          name:              m.name.to_s,
+          scope:             m.scope,
+          visibility:        m.visibility,
+          signature:         m.signature,
+          rbs_signature:     m.rbs_signature,
+
+          docstring:         m.docstring,
+          params:            m.params.map { |p| param_to_hash(p) },
+          options:           m.options.map { |o| option_to_hash(o) },
+          returns:           return_to_hash(m.returns),
+          yields:            yield_to_hash(m.yields),
+          raises:            m.raises.map { |r| raise_to_hash(r) },
+          examples:          m.examples.map { |e| example_to_hash(e) },
+          notes:             m.notes,
+          see_also:          m.see_also.map { |s| see_to_hash(s) },
+
+          api:               m.api,
+          deprecated:        m.deprecated,
+          abstract:          m.abstract,
+          since:             m.since,
+          todo:              m.todo,
+
+          overloads:         m.overloads.map { |o| overload_to_hash(o) },
+
+          source:            m.source,
+          source_body_lines: m.source_body_lines,
+          file:              m.file,
+          line:              m.line
+        }
+      end
+
+      def method_summary(m) = {
+        name:  m.name.to_s,
+        scope: m.scope,
+        line:  m.line
+      }
+
+      def render_document(frontmatter, body_data)
+        lines = []
+
+        # YAML frontmatter
+        lines << "---"
+        lines << frontmatter.to_yaml.sub(/\A---\n/, "").chomp
+        lines << "---"
+        lines << ""
+
+        # Title
+        lines << "# #{frontmatter['title']}"
+        lines << ""
+
+        # Description if present
+        if frontmatter["description"] && !frontmatter["description"].empty?
+          lines << frontmatter["description"]
+          lines << ""
+        end
+
+        # JSON data block
+        lines << "## Semantic Data"
+        lines << ""
+        lines << "```json"
+        lines << JSON.pretty_generate(body_data)
+        lines << "```"
+        lines << ""
+
+        lines.join("\n")
+      end
+
+      def namespace_to_filename(path)
+        stripped = @namespace_strip ? path.sub(/^#{Regexp.escape(@namespace_strip)}/, "") : path
+        parts    = stripped.split("::")
+        kebab    = parts.map { |p| to_kebab_case(p) }
+        "#{kebab.join('/')}.md".sub(%r{^/}, "")
+      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/spec_example_loader.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Chiridion
+  class Engine
+    # Extracts usage examples from RSpec files.
+    #
+    # Parses spec files to find `let` declarations, `subject` blocks, and
+    # test descriptions that can serve as documentation examples.
+    class SpecExampleLoader
+      def initialize(spec_path, verbose, logger)
+        @spec_path = spec_path
+        @verbose   = verbose
+        @logger    = logger
+      end
+
+      # Load spec examples for all spec files.
+      #
+      # @return [Hash{String => Hash}] Class path => { method_examples:, behaviors:, lets:, subjects: }
+      def load
+        examples   = {}
+        spec_files = Dir.glob("#{@spec_path}/**/*_spec.rb")
+
+        return examples if spec_files.empty?
+
+        @logger.info "Loading examples from #{spec_files.size} spec files..." if @verbose
+        spec_files.each { |file| parse_file(file, examples) }
+        examples
+      end
+
+      private
+
+      def parse_file(file, examples)
+        content       = File.read(file)
+        current_class = extract_described_class(content)
+        return unless current_class
+
+        examples[current_class] ||= {
+          method_examples: Hash.new { |h, k| h[k] = [] },
+          behaviors:       Hash.new { |h, k| h[k] = [] },
+          lets:            [],
+          subjects:        []
+        }
+
+        extract_lets(content, examples[current_class])
+        extract_subjects(content, examples[current_class])
+        extract_behaviors(content, examples[current_class])
+      end
+
+      def extract_described_class(content)
+        # Match: RSpec.describe ClassName or describe ClassName
+        return unless content =~ /(?:RSpec\.)?describe\s+([A-Z][\w:]+)/
+
+        Regexp.last_match(1)
+      end
+
+      def extract_lets(content, data)
+        # Match: let(:name) { ... } or let!(:name) { ... }
+        content.scan(/let!?\(:(\w+)\)\s*\{([^}]+)\}/) do |name, code|
+          data[:lets] << { name: name, code: code.strip }
+        end
+      end
+
+      def extract_subjects(content, data)
+        # Match: subject { ... } or subject(:name) { ... }
+        content.scan(/subject(?:\(:(\w+)\))?\s*\{([^}]+)\}/) do |name, code|
+          data[:subjects] << { name: name || "subject", code: code.strip }
+        end
+      end
+
+      def extract_behaviors(content, data)
+        # Match: describe "#method" do or describe ".method" do
+        current_method = nil
+        content.each_line do |line|
+          if line =~ /describe\s+['"](#|\.)\w+['"]/
+            current_method = line[/['"](#|\.)(\w+)['"]/, 0]&.tr("'\"", "")
+          elsif line =~ /it\s+['"]([^'"]+)['"]/ && current_method
+            behavior = Regexp.last_match(1)
+            data[:behaviors][current_method] << behavior
+          end
+        end
+      end
+    end
+  end
+end

data/lib/chiridion/engine/template_renderer.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+require "liquid"
+
+module Chiridion
+  class Engine
+    # Renders documentation using Liquid templates.
+    #
+    # Templates are loaded from the gem's templates/ directory by default,
+    # but can be overridden by specifying a custom templates_path.
+    #
+    # Available templates:
+    # - index.liquid: Documentation index page
+    # - document.liquid: Class/module documentation
+    # - method.liquid: Individual method documentation
+    # - constants.liquid: Constants table and complex constant sections
+    class TemplateRenderer
+      # Custom Liquid filters for documentation rendering.
+      module Filters
+        # Escape pipe characters for markdown table cells.
+        def escape_pipes(input)
+          return "" if input.nil?
+
+          input.to_s.gsub("|", "\\|")
+        end
+
+        # Remove newlines for single-line table cells.
+        def strip_newlines(input)
+          return "" if input.nil?
+
+          input.to_s.gsub(/\s*\n\s*/, " ").strip
+        end
+
+        # Convert to kebab case for file paths.
+        def kebab_case(input)
+          return "" if input.nil?
+
+          input.to_s
+               .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
+
+        # Strip @rbs! blocks from docstrings (type metadata shouldn't be in docs).
+        def strip_rbs_blocks(input)
+          return "" if input.nil?
+
+          input.to_s.gsub(/@rbs![\s\S]*?(?=\n\n|\z)/, "").strip
+        end
+
+        # Normalize markdown headers to be subordinate to a given level.
+        # Usage: {{ docstring | normalize_headers: 4 }}
+        # Adjusts all headers so the minimum level becomes the specified level.
+        def normalize_headers(input, min_level = 3)
+          return "" if input.nil? || input.to_s.empty?
+
+          text  = input.to_s
+          lines = text.lines
+
+          # Find the minimum header level in the text
+          header_levels = lines.filter_map do |line|
+            match = line.match(/^(#+)\s/)
+            match[1].length if match
+          end
+
+          return text if header_levels.empty?
+
+          current_min = header_levels.min
+          offset      = min_level.to_i - current_min
+          return text if offset <= 0
+
+          # Prepend offset number of # to all header lines
+          prefix = "#" * offset
+          lines.map do |line|
+            if line.match?(/^#+\s/)
+              prefix + line
+            else
+              line
+            end
+          end.join
+        end
+      end
+
+      def initialize(templates_path: nil)
+        @templates_path = templates_path || default_templates_path
+        @templates      = {}
+        @environment    = Liquid::Environment.build do |env|
+          env.register_filter(Filters)
+        end
+      end
+
+      # Render the index template.
+      #
+      # @param title [String] Project title
+      # @param description [String] Index description
+      # @param classes [Array<Hash>] Class objects with :path and :link_path
+      # @param modules [Array<Hash>] Module objects with :path and :link_path
+      # @return [String] Rendered markdown
+      def render_index(title:, description:, classes:, modules:)
+        render("index", {
+                 "title"       => title,
+                 "description" => description,
+                 "classes"     => stringify_keys(classes),
+                 "modules"     => stringify_keys(modules)
+               })
+      end
+
+      # Render a class or module document.
+      #
+      # @param title [String] Class/module full path
+      # @param docstring [String] Main documentation (linkified)
+      # @param mixins [String, nil] Mixin line (e.g., "**Includes:** ...")
+      # @param examples [Array<Hash>] YARD examples with :name and :text
+      # @param spec_examples [String, nil] Rendered spec examples section
+      # @param see_also [String, nil] See also links
+      # @param constants_section [String] Rendered constants section
+      # @param types_section [String] Rendered types section (type aliases used by this class)
+      # @param attributes_section [String] Rendered attributes section
+      # @param methods_section [String] Rendered methods section
+      # @return [String] Rendered markdown
+      def render_document(
+        title:,
+        docstring:,
+        mixins: nil,
+        examples: [],
+        spec_examples: nil,
+        see_also: nil,
+        constants_section: "",
+        types_section: "",
+        attributes_section: "",
+        methods_section: ""
+      )
+        render("document", {
+                 "title"              => title,
+                 "docstring"          => docstring,
+                 "mixins"             => mixins,
+                 "examples"           => stringify_keys(examples),
+                 "spec_examples"      => spec_examples,
+                 "see_also"           => see_also,
+                 "constants_section"  => constants_section,
+                 "types_section"      => types_section,
+                 "attributes_section" => attributes_section,
+                 "methods_section"    => methods_section
+               })
+      end
+
+      # Render a single method.
+      #
+      # @param display_name [String] Method name (with class prefix if needed)
+      # @param has_params [Boolean] Whether method has parameters
+      # @param docstring [String, nil] Method description
+      # @param params [Array<String>] Formatted parameter lines
+      # @param return_line [String, nil] Formatted return line
+      # @param examples [Array<Hash>] YARD examples
+      # @param behaviors [Array<String>] Spec behavior descriptions
+      # @param spec_examples [Array<Hash>] Spec code examples
+      # @param inline_source [String, nil] Method source code to display inline
+      # @return [String] Rendered markdown
+      def render_method(
+        display_name:,
+        has_params: false,
+        docstring: nil,
+        params: [],
+        return_line: nil,
+        examples: [],
+        behaviors: [],
+        spec_examples: [],
+        inline_source: nil
+      )
+        render("method", {
+                 "display_name"  => display_name,
+                 "has_params"    => has_params,
+                 "docstring"     => docstring,
+                 "params"        => params,
+                 "return_line"   => return_line,
+                 "examples"      => stringify_keys(examples),
+                 "behaviors"     => behaviors,
+                 "spec_examples" => stringify_keys(spec_examples),
+                 "inline_source" => inline_source
+               })
+      end
+
+      # Render the methods section with separators.
+      #
+      # @param methods [Array<String>] Pre-rendered method strings
+      # @return [String] Rendered markdown
+      def render_methods(methods:) = render("methods", {
+                                              "methods" => methods
+                                            })
+
+      # Render the constants section.
+      #
+      # @param constants [Array<Hash>] Constants with :name, :value, :docstring, :is_complex
+      # @param complex_constants [Array<Hash>] Complex constants for expanded rendering
+      # @return [String] Rendered markdown
+      def render_constants(constants:, complex_constants:)
+        render("constants", {
+                 "constants"         => stringify_keys(constants),
+                 "complex_constants" => stringify_keys(complex_constants)
+               })
+      end
+
+      # Render the types section (type aliases used by a class/module).
+      #
+      # @param types [Array<Hash>] Types with :name, :definition, :description, :namespace
+      # @return [String] Rendered markdown
+      def render_types(types:) = render("types", {
+                                          "types" => stringify_keys(types)
+                                        })
+
+      # Render the type aliases reference page.
+      #
+      # @param title [String] Page title
+      # @param description [String] Page description
+      # @param namespaces [Array<Hash>] Namespaces with :name and :types arrays
+      # @return [String] Rendered markdown
+      def render_type_aliases(title:, description:, namespaces:)
+        render("type_aliases", {
+                 "title"       => title,
+                 "description" => description,
+                 "namespaces"  => stringify_keys(namespaces)
+               })
+      end
+
+      # Render a per-file documentation page.
+      #
+      # @param path [String] Source file path (relative)
+      # @param filename [String] Just the filename
+      # @param line_count [Integer, nil] Total lines in source
+      # @param namespaces [Array<Hash>] Namespace data with pre-rendered sections
+      # @param type_aliases [Array<Hash>] File-level type aliases
+      # @return [String] Rendered markdown
+      def render_file(path:, filename:, line_count: nil, namespaces: [], type_aliases: [])
+        render("file", {
+                 "path"         => path,
+                 "filename"     => filename,
+                 "line_count"   => line_count,
+                 "namespaces"   => stringify_keys(namespaces),
+                 "type_aliases" => stringify_keys(type_aliases)
+               })
+      end
+
+      private
+
+      def default_templates_path = File.expand_path("../../../templates", __dir__)
+
+      def render(template_name, variables)
+        template = load_template(template_name)
+        template.render(variables).strip
+      end
+
+      def load_template(name)
+        @templates[name] ||= begin
+          path = File.join(@templates_path, "#{name}.liquid")
+          raise "Template not found: #{path}" unless File.exist?(path)
+
+          Liquid::Template.parse(File.read(path), environment: @environment)
+        end
+      end
+
+      # Convert symbol keys to string keys for Liquid compatibility.
+      def stringify_keys(obj)
+        case obj
+        when Array
+          obj.map { |item| stringify_keys(item) }
+        when Hash
+          obj.transform_keys(&:to_s).transform_values { |v| stringify_keys(v) }
+        else
+          obj
+        end
+      end
+    end
+  end
+end