docit 0.4.0 → 0.6.0

data/app/controllers/docit/ui_controller.rb

@@ -16,6 +16,17 @@ module Docit
       render_ui(:scalar)
     end
 
+    def system
+      render_ui(:system)
+    end
+
+    def system_spec
+      return render(json: { error: "System graph disabled" }, status: :not_found) unless Docit.configuration.system_graph_enabled
+
+      RouteInspector.eager_load_controllers!
+      render json: SystemGraph::Generator.generate
+    end
+
     def spec
       RouteInspector.eager_load_controllers!
       render json: SchemaGenerator.generate
@@ -25,11 +36,16 @@ module Docit
 
     RENDERERS = {
       swagger: UI::SwaggerRenderer,
-      scalar: UI::ScalarRenderer
+      scalar: UI::ScalarRenderer,
+      system: UI::SystemRenderer
     }.freeze
 
     def render_ui(ui_name)
-      renderer = RENDERERS.fetch(ui_name).new(spec_url: spec_url, nav_paths: nav_paths)
+      renderer = RENDERERS.fetch(ui_name).new(
+        spec_url: spec_url,
+        system_url: system_url,
+        nav_paths: nav_paths
+      )
       render html: renderer.render.html_safe, layout: false
     end
 
@@ -37,9 +53,13 @@ module Docit
       "#{request.base_url}#{Docit::Engine.routes.url_helpers.spec_path}"
     end
 
+    def system_url
+      "#{request.base_url}#{Docit::Engine.routes.url_helpers.system_spec_path}"
+    end
+
     def nav_paths
       helpers = Docit::Engine.routes.url_helpers
-      { swagger: helpers.swagger_path, scalar: helpers.scalar_path }
+      { swagger: helpers.swagger_path, scalar: helpers.scalar_path, system: helpers.system_path }
     end
   end
 end

data/config/routes.rb

@@ -4,5 +4,7 @@ Docit::Engine.routes.draw do
   root to: "ui#index"
   get "swagger", to: "ui#swagger"
   get "scalar", to: "ui#scalar"
+  get "system.json", to: "ui#system_spec", defaults: { format: :json }, as: :system_spec
+  get "system", to: "ui#system", as: :system
   get "spec", to: "ui#spec", defaults: { format: :json }
 end

data/lib/docit/ai/autodoc_runner.rb

@@ -57,9 +57,7 @@ module Docit
         end
 
         initializer = Rails.root.join("config", "initializers", "docit.rb")
-        if File.exist?(initializer) == false
-          raise Docit::Error, "Docit is not installed. Run: rails generate docit:install"
-        end
+        raise Docit::Error, "Docit is not installed. Run: rails generate docit:install" if File.exist?(initializer) == false
 
         routes_file = Rails.root.join("config", "routes.rb")
         return unless File.exist?(routes_file) && !File.read(routes_file).include?("Docit::Engine")
@@ -179,8 +177,15 @@ module Docit
           end
         end
 
+        endpoints = pluralize(@results[:generated], "endpoint")
+        files = pluralize(@results[:files].length, "file")
         @output.puts ""
-        @output.puts "Generated docs for #{@results[:generated]} endpoint#{"s" if @results[:generated] > 1} in #{@results[:files].length} file#{"s" if @results[:files].length > 1}."
+        @output.puts "Generated docs for #{endpoints} in #{files}."
+      end
+
+      # "1 endpoint" / "2 endpoints" — keeps the summary lines short and readable.
+      def pluralize(count, noun)
+        "#{count} #{noun}#{"s" unless count == 1}"
       end
 
       def inject_tags(generated)

data/lib/docit/ai/doc_writer.rb

@@ -20,7 +20,7 @@ module Docit
       end
 
       def doc_module_name
-        @controller_name.delete_suffix("Controller").gsub("::", "::") + "Docs"
+        "#{@controller_name.delete_suffix("Controller").gsub("::", "::")}Docs"
       end
 
       def file_exists?
@@ -44,7 +44,7 @@ module Docit
         match = content.match(class_pattern)
         return false if match.nil?
 
-        indent = match[1][/^\s*/] + "  "
+        indent = "#{match[1][/^\s*/]}  "
         use_docs_line = "#{indent}use_docs #{doc_module_name}\n"
         content = content.sub(class_pattern, "\\1\n#{use_docs_line}")
 
@@ -100,7 +100,7 @@ module Docit
           lines << "#{"  " * (@module_parts.length - 1 - i)}end"
         end
 
-        lines.join("\n") + "\n"
+        "#{lines.join("\n")}\n"
       end
 
       def indent_block(block, depth)

data/lib/docit/ai/groq_client.rb

@@ -59,18 +59,14 @@ module Docit
 
       def parse_retry_after(response, message)
         # Check Retry-After header first (seconds)
-        if (header = response["Retry-After"])
-          return header.to_f if header.to_f > 0
+        if (header = response["Retry-After"]) && header.to_f.positive?
+          return header.to_f
         end
 
         # Parse "try again in XmY.Zs" from error message
-        if message =~ /(\d+)m([\d.]+)s/
-          return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f
-        end
+        return (Regexp.last_match(1).to_i * 60) + Regexp.last_match(2).to_f if message =~ /(\d+)m([\d.]+)s/
 
-        if message =~ /([\d.]+)s/
-          return Regexp.last_match(1).to_f
-        end
+        return Regexp.last_match(1).to_f if message =~ /([\d.]+)s/
 
         nil
       end

data/lib/docit/ai/scaffold_generator.rb

@@ -50,8 +50,10 @@ module Docit
 
         inject_tags(grouped)
 
+        endpoints = "endpoint".pluralize(gaps.length)
+        files = "file".pluralize(@files_written.length)
         @output.puts ""
-        @output.puts "Scaffolded #{gaps.length} endpoint#{"s" if gaps.length > 1} in #{@files_written.length} file#{"s" if @files_written.length > 1}."
+        @output.puts "Scaffolded #{gaps.length} #{endpoints} in #{@files_written.length} #{files}."
         @output.puts "Fill in the TODO placeholders in your doc files."
         @files_written
       end

data/lib/docit/ai/tag_injector.rb

@@ -24,7 +24,7 @@ module Docit
         insertion_point = find_insertion_point(content)
         return [] if insertion_point.nil?
 
-        content = content.insert(insertion_point, "\n#{lines.join("\n")}")
+        content.insert(insertion_point, "\n#{lines.join("\n")}")
         File.write(initializer_path, content)
 
         new_tags

data/lib/docit/builders/response_builder.rb

@@ -3,15 +3,16 @@
 module Docit
   module Builders
     # Builds the schema for a single HTTP response, including properties,
-    # examples, and schema references.
+    # examples, headers, and schema references.
     class ResponseBuilder
-      attr_reader :status, :description, :properties, :examples, :schema_ref
+      attr_reader :status, :description, :properties, :examples, :headers, :schema_ref
 
       def initialize(status:, description:)
         @status = status
         @description = description
         @properties = []
         @examples = []
+        @headers = []
         @schema_ref = nil
       end
 
@@ -19,6 +20,15 @@ module Docit
         @schema_ref = ref.to_sym
       end
 
+      # Declares a response header, e.g. a rate-limit or pagination header:
+      #   header "X-RateLimit-Remaining", type: :integer, description: "..."
+      def header(name, type: :string, description: nil, example: nil)
+        entry = { name: name.to_s, type: type.to_s }
+        entry[:description] = description if description
+        entry[:example] = example unless example.nil?
+        @headers << entry
+      end
+
       def property(name, type:, format: nil, example: nil, enum: nil, description: nil, items: nil, **opts, &block)
         prop = { name: name, type: type }
         prop[:format] = format if format

data/lib/docit/configuration.rb

@@ -5,7 +5,8 @@ module Docit
   class Configuration
     SUPPORTED_UIS = %i[scalar swagger].freeze
 
-    attr_accessor :title, :version, :description, :base_url
+    attr_accessor :title, :version, :description, :base_url,
+                  :system_graph_enabled, :system_graph_excluded_paths
     attr_reader :default_ui
 
     def initialize
@@ -13,6 +14,8 @@ module Docit
       @version = "1.0.0"
       @description = "Welcome to the API documentation. Browse the endpoints below to get started."
       @base_url = "/"
+      @system_graph_enabled = true
+      @system_graph_excluded_paths = []
       @default_ui = :scalar
       @security_schemes = {}
       @tags = []
@@ -24,9 +27,7 @@ module Docit
 
     def default_ui=(value)
       ui = value.to_sym
-      unless SUPPORTED_UIS.include?(ui)
-        raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}"
-      end
+      raise ArgumentError, "Unsupported UI: #{value}. Must be one of: #{SUPPORTED_UIS.join(", ")}" unless SUPPORTED_UIS.include?(ui)
 
       @default_ui = ui
     end

data/lib/docit/schema_generator.rb

@@ -104,10 +104,21 @@ module Docit
           entry[:content] = content
         end
 
+        entry[:headers] = build_response_headers(builder.headers) if builder.headers.any?
+
         hash[builder.status.to_s] = entry
       end
     end
 
+    def build_response_headers(headers)
+      headers.each_with_object({}) do |header, hash|
+        schema = { schema: { type: header[:type] } }
+        schema[:description] = header[:description] if header[:description]
+        schema[:schema][:example] = header[:example] if header.key?(:example)
+        hash[header[:name]] = schema
+      end
+    end
+
     def build_request_body(request_body_builder)
       if request_body_builder.schema_ref
         schema = { "$ref" => "#/components/schemas/#{request_body_builder.schema_ref}" }
@@ -138,43 +149,50 @@ module Docit
 
     def build_property_schema(prop)
       type = prop[:type].to_s
+      schema = base_property_schema(type, prop)
+
+      # These OpenAPI fields apply to any property shape, so set them once here
+      # rather than in each branch above. nil-checks let `false`/`0` through as
+      # explicit values (e.g. default: false), but skip unset options.
+      schema[:description] = prop[:description] if prop[:description]
+      schema[:example] = prop[:example] if prop[:example]
+      schema[:default] = prop[:default] unless prop[:default].nil?
+      schema[:nullable] = prop[:nullable] unless prop[:nullable].nil?
+      schema[:readOnly] = prop[:read_only] unless prop[:read_only].nil?
+      schema[:writeOnly] = prop[:write_only] unless prop[:write_only].nil?
+      schema
+    end
 
-      if type == "file"
-        schema = { type: "string", format: "binary" }
-        schema[:description] = prop[:description] if prop[:description]
-        schema
-      elsif type == "array"
-        schema = { type: "array" }
-        if prop[:children]
-          schema[:items] = {
-            type: "object",
-            properties: build_properties(prop[:children])
-          }
+    def base_property_schema(type, prop)
+      case type
+      when "file"
+        { type: "string", format: "binary" }
+      when "array"
+        { type: "array", items: array_items_schema(prop) }
+      else
+        # An object with declared children becomes a nested schema; everything
+        # else (including a childless "object") is a scalar with type/format/enum.
+        if type == "object" && prop[:children]
+          { type: "object", properties: build_properties(prop[:children]) }
         else
-          items_type = prop[:items]&.to_s || "string"
-          schema[:items] = { type: items_type }
+          scalar_property_schema(type, prop)
         end
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      elsif type == "object" && prop[:children]
-        schema = {
-          type: "object",
-          properties: build_properties(prop[:children])
-        }
-        schema[:description] = prop[:description] if prop[:description]
-        schema[:example] = prop[:example] if prop[:example]
-        schema
-      else
-        schema = { type: type }
-        schema[:format] = prop[:format].to_s if prop[:format]
-        schema[:enum] = prop[:enum] if prop[:enum]
-        schema[:example] = prop[:example] if prop[:example]
-        schema[:description] = prop[:description] if prop[:description]
-        schema
       end
     end
 
+    def array_items_schema(prop)
+      return { type: "object", properties: build_properties(prop[:children]) } if prop[:children]
+
+      { type: prop[:items]&.to_s || "string" }
+    end
+
+    def scalar_property_schema(type, prop)
+      schema = { type: type }
+      schema[:format] = prop[:format].to_s if prop[:format]
+      schema[:enum] = prop[:enum] if prop[:enum]
+      schema
+    end
+
     def build_component_schemas
       Docit.schemas.each_with_object({}) do |(name, definition), hash|
         schema = {

data/lib/docit/system_graph/edge.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Edge
+      attr_reader :id, :source, :target, :type, :confidence, :evidence
+
+      def initialize(id:, source:, target:, type:, confidence:, evidence:)
+        @id = id.to_s
+        @source = source.to_s
+        @target = target.to_s
+        @type = type.to_s
+        @confidence = confidence.to_s
+        @evidence = evidence.to_s
+      end
+
+      def to_h
+        {
+          id: id,
+          source: source,
+          target: target,
+          type: type,
+          confidence: confidence,
+          evidence: evidence
+        }
+      end
+    end
+  end
+end

data/lib/docit/system_graph/generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Generator
+      def self.generate
+        new.generate
+      end
+
+      def generate
+        RailsAnalyzer.new.analyze.to_h
+      end
+    end
+  end
+end

data/lib/docit/system_graph/graph.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Docit
+  module SystemGraph
+    class Graph
+      VERSION = "1.0"
+
+      attr_reader :nodes, :edges, :framework
+
+      def initialize(framework: "rails")
+        @framework = framework
+        @nodes = {}
+        @edges = {}
+      end
+
+      def add_node(node)
+        nodes[node.id] ||= node
+      end
+
+      def add_edge(edge)
+        return if edge.source == edge.target
+        return unless nodes.key?(edge.source) && nodes.key?(edge.target)
+
+        edges[edge.id] ||= edge
+      end
+
+      def to_h
+        node_values = nodes.values
+        edge_values = edges.values
+
+        {
+          version: VERSION,
+          generated_at: Time.now.utc.iso8601,
+          framework: framework,
+          nodes: node_values.map(&:to_h),
+          edges: edge_values.map(&:to_h),
+          stats: stats(node_values, edge_values)
+        }
+      end
+
+      private
+
+      def stats(node_values, edge_values)
+        {
+          nodes: node_values.length,
+          edges: edge_values.length,
+          node_types: node_values.group_by(&:type).transform_values(&:length),
+          edge_types: edge_values.group_by(&:type).transform_values(&:length)
+        }
+      end
+    end
+  end
+end

data/lib/docit/system_graph/node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Docit
+  module SystemGraph
+    class Node
+      attr_reader :id, :type, :label, :metadata, :file, :line, :status
+
+      def initialize(id:, type:, label:, metadata: {}, file: nil, line: nil, status: nil)
+        @id = id.to_s
+        @type = type.to_s
+        @label = label.to_s
+        @metadata = metadata
+        @file = file
+        @line = line
+        @status = status
+      end
+
+      def to_h
+        {
+          id: id,
+          type: type,
+          label: label,
+          metadata: metadata
+        }.tap do |hash|
+          hash[:file] = file if file
+          hash[:line] = line if line
+          hash[:status] = status if status
+        end
+      end
+    end
+  end
+end