docit 0.1.0 → 0.2.0

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,55 @@
+# 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"
+          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
+    end
+  end
+end

data/lib/docit/ai/openai_client.rb

@@ -0,0 +1,55 @@
+# 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"
+          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.0"
 end

data/lib/docit.rb

@@ -46,3 +46,5 @@ module Docit
     end
   end
 end
+
+require_relative "docit/ai"

data/lib/generators/docit/ai_setup/ai_setup_generator.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Docit
+  module Generators
+    class AiSetupGenerator < Rails::Generators::Base
+      desc "Configures AI provider for Docit autodoc generation"
+
+      PROVIDER_OPTIONS = {
+        "1" => "openai",
+        "2" => "anthropic",
+        "3" => "groq"
+      }.freeze
+
+      def prompt_provider
+        say ""
+        say "Select your AI provider:"
+        say "  1. OpenAI"
+        say "  2. Anthropic"
+        say "  3. Groq (free tier available)"
+        say ""
+
+        choice = ask_choice("Enter choice (1-3):", PROVIDER_OPTIONS.keys)
+        @provider = PROVIDER_OPTIONS[choice]
+
+        say "Selected: #{@provider.capitalize}", :green
+      end
+
+      def prompt_api_key
+        loop do
+          @api_key = ask_secret("Enter your #{@provider.capitalize} API key:")
+          return if @api_key.empty? == false
+
+          say "API key cannot be blank", :red
+        end
+      end
+
+      def save_configuration
+        model = Docit::Ai::Configuration::DEFAULT_MODELS[@provider]
+        Docit::Ai::Configuration.save(
+          provider: @provider,
+          model: model,
+          api_key: @api_key
+        )
+        say "Saved AI configuration to .docit_ai.yml", :green
+      end
+
+      def update_gitignore
+        gitignore = Rails.root.join(".gitignore")
+        if File.exist?(gitignore) == false
+          say "Warning: .gitignore not found. Add .docit_ai.yml manually to avoid committing your API key.", :yellow
+          return
+        end
+
+        content = File.read(gitignore)
+        return if content.include?(".docit_ai.yml")
+
+        File.open(gitignore, "a") do |f|
+          f.puts "" if content.end_with?("\n") == false
+          f.puts "# Docit AI configuration (contains API key)"
+          f.puts ".docit_ai.yml"
+        end
+        say "Added .docit_ai.yml to .gitignore", :green
+      end
+
+      def print_instructions
+        say ""
+        say "Docit AI configured successfully!", :green
+        say ""
+        say "Docit stores your API key in .docit_ai.yml with restricted file permissions."
+        say "Keep that file out of version control."
+        say ""
+        say "Next steps:"
+        say "  rails docit:autodoc                              # document all undocumented endpoints"
+        say "  rails docit:autodoc[Api::V1::UsersController]    # document a specific controller"
+        say "  DRY_RUN=1 rails docit:autodoc                    # preview without writing files"
+        say ""
+        say "To reconfigure, run this generator again."
+        say ""
+      end
+
+      private
+
+      def ask_choice(prompt, choices)
+        loop do
+          choice = ask(prompt).to_s.strip
+          return choice if choices.include?(choice)
+
+          say "Invalid choice. Please enter #{choices.join(", ")}.", :red
+        end
+      end
+
+      def ask_secret(prompt)
+        if $stdin.respond_to?(:noecho) && $stdin.tty?
+          shell.say(prompt, nil, false)
+          value = $stdin.noecho(&:gets).to_s.strip
+          shell.say("")
+          value
+        else
+          ask(prompt).to_s.strip
+        end
+      end
+    end
+  end
+end