docit 0.1.0 → 0.2.1

data/lib/docit/ai/doc_writer.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "active_support/core_ext/string/inflections"
+
+module Docit
+  module Ai
+    class DocWriter
+      def initialize(controller_name:)
+        @controller_name = controller_name
+        @module_parts = build_module_parts
+      end
+
+      def doc_file_path
+        parts = @controller_name.underscore.delete_suffix("_controller").split("/")
+        filename = "#{parts.last}_docs.rb"
+        dir_parts = parts[0..-2]
+
+        File.join(Rails.root, "app", "docs", *dir_parts, filename)
+      end
+
+      def doc_module_name
+        @controller_name.delete_suffix("Controller").gsub("::", "::") + "Docs"
+      end
+
+      def file_exists?
+        File.exist?(doc_file_path)
+      end
+
+      def controller_has_use_docs?
+        path = controller_file_path
+        return false if path && File.exist?(path) == false
+
+        File.read(path).include?("use_docs")
+      end
+
+      def inject_use_docs
+        path = controller_file_path
+        return false if path && File.exist?(path) == false
+        return false if controller_has_use_docs?
+
+        content = File.read(path)
+        class_pattern = /^(\s*class\s+\S+.*$)/
+        match = content.match(class_pattern)
+        return false if match.nil?
+
+        indent = match[1][/^\s*/] + "  "
+        use_docs_line = "#{indent}use_docs #{doc_module_name}\n"
+        content = content.sub(class_pattern, "\\1\n#{use_docs_line}")
+
+        File.write(path, content)
+        true
+      end
+
+      def write(doc_blocks)
+        if file_exists?
+          append_to_existing(doc_blocks)
+        else
+          create_new_file(doc_blocks)
+        end
+      end
+
+      private
+
+      def create_new_file(doc_blocks)
+        FileUtils.mkdir_p(File.dirname(doc_file_path))
+
+        content = build_new_file_content(doc_blocks)
+        File.write(doc_file_path, content)
+      end
+
+      def append_to_existing(doc_blocks)
+        content = File.read(doc_file_path)
+        insertion = doc_blocks.map { |block| indent_block(block, @module_parts.length + 1) }.join("\n\n")
+        closing_ends = "end\n" * @module_parts.length
+
+        content = content.rstrip
+        content = content.delete_suffix(closing_ends.rstrip)
+        content = "#{content.rstrip}\n\n#{insertion}\n#{closing_ends}"
+
+        File.write(doc_file_path, content)
+      end
+
+      def build_new_file_content(doc_blocks)
+        lines = ["# frozen_string_literal: true", ""]
+
+        @module_parts.each_with_index do |part, i|
+          lines << "#{"  " * i}module #{part}"
+        end
+
+        depth = @module_parts.length
+        lines << "#{"  " * depth}extend Docit::DocFile"
+
+        doc_blocks.each do |block|
+          lines << ""
+          lines << indent_block(block, depth)
+        end
+
+        @module_parts.length.times do |i|
+          lines << "#{"  " * (@module_parts.length - 1 - i)}end"
+        end
+
+        lines.join("\n") + "\n"
+      end
+
+      def indent_block(block, depth)
+        prefix = "  " * depth
+        block.strip.lines.map { |line| line.rstrip.empty? ? "" : "#{prefix}#{line.rstrip}" }.join("\n")
+      end
+
+      def build_module_parts
+        doc_module_name.split("::")
+      end
+
+      def controller_file_path
+        Rails.root.join("app", "controllers", "#{@controller_name.underscore}.rb").to_s
+      end
+    end
+  end
+end

data/lib/docit/ai/gap_detector.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class GapDetector
+      SKIP_PREFIXES = %w[docit/ rails/ active_storage/ action_mailbox/].freeze
+
+      def initialize(controller_filter: nil)
+        @controller_filter = controller_filter
+      end
+
+      def detect
+        RouteInspector.eager_load_controllers!
+
+        all_routes.each_with_object([]) do |route_info, gaps|
+          controller = route_info[:controller]
+          action = route_info[:action]
+
+          next if Registry.find(controller: controller, action: action)
+
+          routes = RouteInspector.routes_for(controller, action)
+          next if routes.empty?
+
+          gaps << {
+            controller: controller,
+            action: action,
+            path: routes.first[:path],
+            method: routes.first[:method]
+          }
+        end
+      end
+
+      private
+
+      def all_routes
+        Rails.application.routes.routes.filter_map do |route|
+          controller_path = route.defaults[:controller]
+          action = route.defaults[:action]
+          next if controller_path.nil? || action.nil?
+          next if skip_route?(controller_path)
+
+          controller_class = "#{controller_path}_controller".camelize
+          next if @controller_filter && controller_class != @controller_filter
+
+          { controller: controller_class, action: action }
+        end.uniq
+      end
+
+      def skip_route?(controller_path)
+        SKIP_PREFIXES.any? { |prefix| controller_path.start_with?(prefix) }
+      end
+    end
+  end
+end

data/lib/docit/ai/groq_client.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Docit
+  module Ai
+    class GroqClient
+      API_URL = "https://api.groq.com/openai/v1/chat/completions"
+
+      def initialize(api_key:, model:)
+        @api_key = api_key
+        @model = model
+      end
+
+      def generate(prompt)
+        uri = URI(API_URL)
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = {
+          model: @model,
+          messages: [{ role: "user", content: prompt }],
+          temperature: 0.2
+        }.to_json
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 15, read_timeout: 60) do |http|
+          http.request(request)
+        end
+
+        handle_response(response)
+      end
+
+      private
+
+      def handle_response(response)
+        body = parse_json(response, "Groq")
+
+        if response.is_a?(Net::HTTPSuccess) == false
+          message = body.dig("error", "message") || "Unknown API error"
+
+          if response.code == "429"
+            retry_after = parse_retry_after(response, message)
+            raise RateLimitError.new("Groq rate limit exceeded", retry_after: retry_after)
+          end
+
+          raise Error, "Groq API error (#{response.code}): #{message}"
+        end
+
+        body.dig("choices", 0, "message", "content") || raise(Error, "Empty response from Groq")
+      end
+
+      def parse_json(response, provider_name)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "#{provider_name} returned invalid JSON (HTTP #{response.code})"
+      end
+
+      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
+        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
+
+        if message =~ /([\d.]+)s/
+          return Regexp.last_match(1).to_f
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/docit/ai/openai_client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Docit
+  module Ai
+    class OpenaiClient
+      API_URL = "https://api.openai.com/v1/chat/completions"
+
+      def initialize(api_key:, model:)
+        @api_key = api_key
+        @model = model
+      end
+
+      def generate(prompt)
+        uri = URI(API_URL)
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = {
+          model: @model,
+          messages: [{ role: "user", content: prompt }],
+          temperature: 0.2
+        }.to_json
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true, open_timeout: 15, read_timeout: 60) do |http|
+          http.request(request)
+        end
+
+        handle_response(response)
+      end
+
+      private
+
+      def handle_response(response)
+        body = parse_json(response, "OpenAI")
+
+        if response.is_a?(Net::HTTPSuccess) == false
+          message = body.dig("error", "message") || "Unknown API error"
+
+          if response.code == "429"
+            retry_after = response["Retry-After"]&.to_f
+            raise RateLimitError.new("OpenAI rate limit exceeded", retry_after: retry_after)
+          end
+
+          raise Error, "OpenAI API error (#{response.code}): #{message}"
+        end
+
+        body.dig("choices", 0, "message", "content") || raise(Error, "Empty response from OpenAI")
+      end
+
+      def parse_json(response, provider_name)
+        JSON.parse(response.body)
+      rescue JSON::ParserError
+        raise Error, "#{provider_name} returned invalid JSON (HTTP #{response.code})"
+      end
+    end
+  end
+end

data/lib/docit/ai/prompt_builder.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class PromptBuilder
+      DSL_REFERENCE = <<~DSL
+        Available DSL methods inside a `doc :action_name do ... end` block:
+          summary "Short description"
+          description "Detailed description"
+          tags "TagName"
+          deprecated value: true
+          security :bearer_auth
+
+          parameter :name, location: :query|:path|:header, type: :string|:integer|:boolean, required: true/false, description: "..."
+          parameter :id, location: :path, type: :string, required: true
+
+          request_body required: true do
+            property :field, type: :string|:integer|:boolean|:array|:object|:file, required: true/false, example: "value"
+            property :field, type: :string, enum: %w[option1 option2]
+            property :nested, type: :object do
+              property :child, type: :string
+            end
+            property :items, type: :array do
+              property :id, type: :string
+            end
+          end
+
+          response 200, "Description" do
+            property :field, type: :string, example: "value"
+            property :nested, type: :object do
+              property :child, type: :string
+            end
+          end
+          response 404, "Not found" do
+            property :error, type: :string, example: "Not found"
+          end
+      DSL
+
+      EXAMPLE_DOC = <<~EXAMPLE
+        doc :register do
+          summary "Register a new user"
+          description "Creates a customer account and sends verification email"
+          tags "Authentication"
+
+          request_body required: true do
+            property :email, type: :string, required: true, example: "user@example.com"
+            property :password, type: :string, required: true, format: :password
+            property :full_name, type: :string, required: true, example: "John Doe"
+            property :role, type: :string, enum: %w[customer provider]
+          end
+
+          response 201, "Account created successfully" do
+            property :user_id, type: :string, example: "123e4567-e89b-12d3-a456-426614174000"
+            property :email, type: :string, example: "user@example.com"
+          end
+
+          response 422, "Validation error" do
+            property :errors, type: :object do
+              property :email, type: :array, items: :string
+            end
+          end
+        end
+      EXAMPLE
+
+      def initialize(gap:)
+        @gap = gap
+      end
+
+      def build
+        <<~PROMPT
+          You are generating Docit DSL documentation for a Ruby on Rails API endpoint.
+
+          #{DSL_REFERENCE}
+
+          Here is a complete example of a well-documented endpoint:
+          #{EXAMPLE_DOC}
+
+          Now generate documentation for:
+          - Controller: #{@gap[:controller]}
+          - Action: #{@gap[:action]}
+          - HTTP method: #{@gap[:method].upcase}
+          - Path: #{@gap[:path]}
+
+          Controller source code:
+          ```ruby
+          #{controller_source}
+          ```
+
+          Rules:
+          - Output ONLY the `doc :#{@gap[:action]} do ... end` block
+          - No module wrapper, no explanation, no markdown fences
+          - Infer parameters from the path (e.g., {id} → path parameter)
+          - Infer request body from params usage in the controller
+          - Infer response structure from render calls
+          - Use realistic examples
+          - Include appropriate error responses
+          - Use the controller name to determine appropriate tags
+        PROMPT
+      end
+
+      def source_available?
+        path = controller_file_path
+        path && File.exist?(path)
+      end
+
+      private
+
+      def controller_source
+        path = controller_file_path
+        return "# Source not available" if path && File.exist?(path) == false
+        return "# Source not available" if path.nil?
+
+        File.read(path)
+      end
+
+      def controller_file_path
+        return nil if defined?(Rails) == false || Rails.respond_to?(:root) == false || Rails.root.nil?
+
+        relative = @gap[:controller].underscore
+        Rails.root.join("app", "controllers", "#{relative}.rb").to_s
+      end
+    end
+  end
+end

data/lib/docit/ai/scaffold_generator.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "active_support/core_ext/string/inflections"
+
+module Docit
+  module Ai
+    class ScaffoldGenerator
+      def initialize(output: $stdout)
+        @output = output
+        @files_written = []
+      end
+
+      def run
+        check_base_setup!
+        gaps = detect_gaps
+
+        if gaps.empty?
+          @output.puts "No undocumented endpoints found."
+          return @files_written
+        end
+
+        @output.puts "Found #{gaps.length} endpoint#{"s" if gaps.length > 1} to scaffold:"
+        gaps.each { |g| @output.puts "  #{g[:method].upcase} #{g[:path]} (#{g[:controller]}##{g[:action]})" }
+        @output.puts ""
+
+        grouped = gaps.group_by { |g| g[:controller] }
+
+        grouped.each do |controller, controller_gaps|
+          writer = DocWriter.new(controller_name: controller)
+
+          if writer.file_exists?
+            existing_actions = existing_doc_actions(writer.doc_file_path)
+            controller_gaps = controller_gaps.reject { |g| existing_actions.include?(g[:action]) }
+            next if controller_gaps.empty?
+          end
+
+          blocks = controller_gaps.map { |gap| build_placeholder(gap, controller) }
+          writer.write(blocks)
+          @files_written << writer.doc_file_path
+
+          relative = writer.doc_file_path.sub("#{Rails.root}/", "")
+          @output.puts "  Created: #{relative}"
+
+          if writer.inject_use_docs
+            controller_relative = File.join("app", "controllers", "#{controller.underscore}.rb")
+            @output.puts "  Added use_docs to #{controller_relative}"
+          end
+        end
+
+        inject_tags(grouped)
+
+        @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 "Fill in the TODO placeholders in your doc files."
+        @files_written
+      end
+
+      private
+
+      def detect_gaps
+        RouteInspector.eager_load_controllers!
+
+        detector = GapDetector.new
+        detector.detect
+      end
+
+      def check_base_setup!
+        unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+          raise Docit::Error, "Docit requires a Rails application. Run this command from your app root."
+        end
+
+        initializer = Rails.root.join("config", "initializers", "docit.rb")
+        return unless File.exist?(initializer) == false
+
+        raise Docit::Error, "Docit is not installed. Run: rails generate docit:install"
+      end
+
+      def build_placeholder(gap, controller)
+        tag = derive_tag(controller)
+        method = gap[:method].upcase
+        path = gap[:path]
+
+        lines = []
+        lines << "doc :#{gap[:action]} do"
+        lines << "  summary \"TODO: #{method} #{path}\""
+        lines << "  tags \"#{tag}\""
+
+        if gap[:path].include?("{")
+          path_params = gap[:path].scan(/\{(\w+)\}/).flatten
+          path_params.each do |param|
+            lines << "  parameter :#{param}, location: :path, type: :string, required: true"
+          end
+        end
+
+        if %w[POST PUT PATCH].include?(method)
+          lines << ""
+          lines << "  request_body required: true do"
+          lines << "    # TODO: Add request properties"
+          lines << "    # property :name, type: :string, required: true"
+          lines << "  end"
+        end
+
+        lines << ""
+        lines << "  response #{default_status(method)}, \"TODO: Add description\" do"
+        lines << "    # TODO: Add response properties"
+        lines << "    # property :id, type: :integer"
+        lines << "  end"
+        lines << "end"
+
+        lines.join("\n")
+      end
+
+      def derive_tag(controller)
+        controller.delete_suffix("Controller").split("::").last
+      end
+
+      def default_status(method)
+        case method
+        when "POST" then 201
+        when "DELETE" then 204
+        else 200
+        end
+      end
+
+      def existing_doc_actions(path)
+        content = File.read(path)
+        content.scan(/doc\s+:(\w+)/).flatten
+      end
+
+      def inject_tags(grouped)
+        tags = grouped.keys.map { |c| derive_tag(c) }.uniq
+        return if tags.empty?
+
+        injected = TagInjector.new(tags: tags).inject
+        injected.each { |tag| @output.puts "  Added tag \"#{tag}\" to config/initializers/docit.rb" }
+      end
+    end
+  end
+end

data/lib/docit/ai/tag_injector.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Docit
+  module Ai
+    class TagInjector
+      def initialize(tags:)
+        @tags = tags.uniq
+      end
+
+      def inject
+        return [] if initializer_path && File.exist?(initializer_path) == false
+
+        content = File.read(initializer_path)
+        existing_tags = content.scan(/config\.tag\s+["']([^"']+)["']/).flatten
+
+        new_tags = @tags - existing_tags
+        return [] if new_tags.empty?
+
+        lines = new_tags.map do |tag|
+          desc = "#{tag} management endpoints"
+          "  config.tag \"#{tag}\", description: \"#{desc}\""
+        end
+
+        insertion_point = find_insertion_point(content)
+        return [] if insertion_point.nil?
+
+        content = content.insert(insertion_point, "\n#{lines.join("\n")}")
+        File.write(initializer_path, content)
+
+        new_tags
+      end
+
+      private
+
+      def initializer_path
+        return nil if defined?(Rails) == false
+
+        Rails.root.join("config", "initializers", "docit.rb").to_s
+      end
+
+      def find_insertion_point(content)
+        last_tag = content.rindex(/config\.tag\s+/)
+        if last_tag
+          content.index("\n", last_tag)
+        else
+          last_config = content.rindex(/config\.\w+/)
+          content.index("\n", last_config) if last_config
+        end
+      end
+    end
+  end
+end

data/lib/docit/ai.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative "ai/configuration"
+require_relative "ai/client"
+require_relative "ai/openai_client"
+require_relative "ai/anthropic_client"
+require_relative "ai/groq_client"
+require_relative "ai/gap_detector"
+require_relative "ai/prompt_builder"
+require_relative "ai/doc_writer"
+require_relative "ai/tag_injector"
+require_relative "ai/autodoc_runner"
+require_relative "ai/scaffold_generator"

data/lib/docit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docit
-  VERSION = "0.1.0"
+  VERSION = "0.2.1"
 end

data/lib/docit.rb

@@ -46,3 +46,6 @@ module Docit
     end
   end
 end
+
+require_relative "docit/engine" if defined?(Rails::Engine)
+require_relative "docit/ai"