docwright 0.1.0

data/lib/docwright/extractors/auth_extractor.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class AuthExtractor # rubocop:disable Style/Documentation
+      CALLBACK_KINDS = %i[before around after].freeze
+      def generate
+        Rails.application.eager_load!
+
+        controllers = find_controllers
+        filter_map = build_filter_map(controllers)
+        unprotected = find_unprotected(controllers)
+
+        lines = build_lines(filter_map, unprotected, controllers)
+
+        FileUtils.mkdir_p("docs")
+        Docwright::Merger.write("docs/auth_and_permissions.md", lines.join("\n"))
+        puts "DocWright: wrote docs/auth_and_permissions.md"
+      end
+
+      private
+
+      def find_controllers
+        ActionController::Base.descendants
+                              .reject { |c| c.abstract? rescue false } # rubocop:disable Style/RescueModifier
+                              .reject { |c| c.name.nil? }
+                              .reject { |c| c.name.start_with?("ActionController", "ActiveStorage", "Rails") }
+                              .sort_by(&:name)
+      end
+
+      def build_filter_map(controllers) # rubocop:disable Metrics/MethodLength
+        filter_map = {}
+
+        controllers.each do |controller|
+          CALLBACK_KINDS.each do |kind|
+            before_actions = controller._process_action_callbacks.select { |cb| cb.kind == kind }
+
+            before_actions.each do |cb|
+              filter_name = cb.filter.to_s
+              next if cb.filter.is_a?(Proc)
+              next if filter_name.start_with?("verify_authenticity_token", "verify_same_origin_request")
+
+              filter_map[filter_name] ||= { kind: kind, usages: [] }
+              filter_map[filter_name][:usages] << {
+                controller: controller.name,
+                callback: cb
+              }
+            end
+          end
+        end
+
+        filter_map
+      end
+
+      def find_unprotected(controllers)
+        controllers.select do |controller|
+          controller._process_action_callbacks.none? { |cb| cb.kind == :before }
+        end
+      end
+
+      def build_lines(filter_map, unprotected, controllers) # rubocop:disable Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/MethodLength,Metrics/PerceivedComplexity
+        lines = ["# Authentication & Permissions\n"]
+
+        CALLBACK_KINDS.each do |kind|
+          kind_filters = filter_map.select { |_, v| v[:kind] == kind }
+          next if kind_filters.empty?
+
+          lines << "## #{kind.to_s.capitalize} Action Filters\n"
+
+          kind_filters.each do |filter_name, data|
+            lines << "### #{filter_name}"
+            defined_in = detect_origin(filter_name)
+            lines << "- Defined in: #{defined_in}" if defined_in
+
+            data[:usages].each do |usage|
+              conditions = format_conditions(usage[:callback])
+              lines << "- Applied to: #{usage[:controller]}#{conditions}"
+            end
+            lines << ""
+          end
+        end
+
+        unless unprotected.empty?
+          lines << "## Unprotected Controllers\n"
+          unprotected.each do |c|
+            lines << "- #{c.name} — no before_action filters detected"
+          end
+          lines << ""
+        end
+
+        lines << "## Summary\n"
+        lines << "- Total controllers: #{controllers.size}"
+        lines << "- Protected: #{controllers.size - unprotected.size}"
+        lines << "- Unprotected: #{unprotected.size}"
+
+        lines
+      end
+
+      def detect_origin(filter_name)
+        "ApplicationController" if ApplicationController.method_defined?(filter_name.to_sym)
+      rescue NameError
+        nil
+      end
+
+      def format_conditions(cb)
+        conditions = cb.instance_variable_get(:@if) || []
+        parts = []
+
+        conditions.each do |condition|
+          next unless condition.class.name.to_s.include?("ActionFilter")
+
+          key = condition.instance_variable_get(:@conditional_key)
+          actions = condition.instance_variable_get(:@actions).to_a
+          parts << "#{key}: #{actions.join(", ")}" if actions.any?
+        end
+
+        parts.empty? ? "" : " (#{parts.join(", ")})"
+      end
+    end
+  end
+end

data/lib/docwright/extractors/background_jobs_extractor.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class BackgroundJobsExtractor
+      INTERNAL_JOBS = %w[ApplicationJob].freeze
+
+      def generate
+        Rails.application.eager_load!
+
+        jobs = find_jobs
+        if jobs.empty?
+          puts "DocWright: no background jobs found — skipping background_jobs.md"
+          return
+        end
+
+        priorities = load_queue_priorities
+        schedules = load_schedules
+
+        FileUtils.mkdir_p("docs")
+
+        jobs.each do |job|
+          lines = build_job_lines(job, priorities, schedules)
+          notes = "#### Notes for #{job.name}\n<!-- Describe what triggers this job, retry behavior, dependencies -->"
+          Docwright::Merger.write_named("docs/background_jobs.md", job.name, lines.join("\n"), notes)
+        end
+
+        summary_lines = build_summary_lines(jobs, priorities, schedules)
+        Docwright::Merger.write_named("docs/background_jobs.md", "_summary", summary_lines.join("\n"), "")
+
+        puts "DocWright: wrote docs/background_jobs.md"
+      rescue NameError => e
+        raise unless e.message.include?("ActiveJob")
+
+        puts "DocWright: skipped background_jobs.md — ActiveJob is not loaded."
+        puts "  To enable: uncomment 'require \"active_job/railtie\"' in config/application.rb"
+      end
+
+      private
+
+      def find_jobs
+        ActiveJob::Base.descendants
+                       .reject { |j| INTERNAL_JOBS.include?(j.name) }
+                       .reject { |j| j.name.nil? }
+                       .sort_by(&:name)
+      end
+
+      def load_queue_priorities
+        path = "config/sidekiq.yml"
+        return {} unless File.exist?(path)
+
+        require "yaml"
+        config = YAML.load_file(path)
+        return {} unless config.is_a?(Hash)
+
+        queues = config[:queues] || config["queues"] || []
+        queues.each_with_object({}) do |entry, hash|
+          hash[entry[0].to_s] = entry[1]
+        end
+      end
+
+      def load_schedules
+        schedules = {}
+        schedules.merge!(load_whenever_schedules)
+        schedules.merge!(load_solid_queue_schedules)
+        schedules
+      end
+
+      def load_whenever_schedules
+        path = "config/schedule.rb"
+        return {} unless File.exist?(path)
+
+        schedules = {}
+        current_schedule = nil
+        File.readlines(path).each do |line|
+          if line =~ /every\s+(.+)\s+do/
+            current_schedule = ::Regexp.last_match(1).strip
+          elsif line =~ /runner\s+["'](.+Job)/
+            job_name = ::Regexp.last_match(1).strip
+            schedules[job_name] = current_schedule if current_schedule
+          end
+        end
+
+        schedules
+      end
+
+      def load_solid_queue_schedules
+        path = "config/recurring.yml"
+        return {} unless File.exist?(path)
+
+        require "yaml"
+        config = YAML.load_file(path)
+        return {} unless config.is_a?(Hash)
+
+        config.each_with_object({}) do |(_, v), hash|
+          hash[v["class"]] = v["schedule"] if v["class"] && v["schedule"]
+        end
+      end
+
+      def build_job_lines(job, priorities, schedules)
+        queue = job.queue_name.to_s
+        priority = priorities[queue]
+        queue_display = priority ? "#{queue} (priority: #{priority})" : queue
+        schedule = schedules[job.name] || "not scheduled"
+        path = "app/jobs/#{job.name.underscore}.rb"
+
+        lines = []
+        lines << "#### #{job.name}"
+        lines << "- Queue: #{queue_display}"
+        lines << "- Schedule: #{schedule}"
+        lines << "- Defined in: #{path}"
+        lines
+      end
+
+      def build_summary_lines(jobs, priorities, schedules)
+        scheduled = jobs.select { |j| schedules.key?(j.name) }
+        unscheduled = jobs.reject { |j| schedules.key?(j.name) }
+        queues_used = jobs.map(&:queue_name).map(&:to_s).uniq.sort
+
+        lines = ["### Background Jobs Summary\n"]
+
+        unless priorities.empty?
+          lines << "### Queue priorities (from config/sidekiq.yml)"
+          priorities.each { |q, p| lines << "- #{q} — priority: #{p}" }
+          lines << ""
+        end
+
+        unless scheduled.empty?
+          lines << "### Scheduled jobs"
+          scheduled.each { |j| lines << "- #{j.name} — #{schedules[j.name]}" }
+          lines << ""
+        end
+
+        unless unscheduled.empty?
+          lines << "### Unscheduled jobs"
+          unscheduled.each { |j| lines << "- #{j.name}" }
+          lines << ""
+        end
+
+        lines << "### Summary"
+        lines << "- Total jobs: #{jobs.size}"
+        lines << "- Queues used: #{queues_used.join(", ")}"
+        lines << "- Scheduled: #{scheduled.size}"
+        lines << "- Unscheduled: #{unscheduled.size}"
+        lines
+      end
+    end
+  end
+end

data/lib/docwright/extractors/concerns_extractor.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class ConcernsExtractor
+      def generate
+        Rails.application.eager_load!
+
+        concerns = find_model_concerns + find_controller_concerns
+
+        if concerns.empty?
+          puts "DocWright: no concerns found — skipping concerns.md"
+          return
+        end
+
+        FileUtils.mkdir_p("docs")
+
+        concerns.each do |concern|
+          lines = build_concern_lines(concern)
+          notes = "#### Notes for #{concern[:name]}\n<!-- Describe what this concern adds and why it was extracted -->"
+          Docwright::Merger.write_named("docs/concerns.md", concern[:name], lines.join("\n"), notes)
+        end
+
+        model_concerns = concerns.count { |c| c[:type] == "Model Concern" }
+        controller_concerns = concerns.count { |c| c[:type] == "Controller Concern" }
+
+        summary_lines = [
+          "### Summary",
+          "- Total concerns: #{concerns.size}",
+          "- Model concerns: #{model_concerns}",
+          "- Controller concerns: #{controller_concerns}"
+        ]
+        Docwright::Merger.write_named("docs/concerns.md", "_summary", summary_lines.join("\n"), "")
+
+        puts "DocWright: wrote docs/concerns.md"
+      end
+
+      private
+
+      def find_model_concerns
+        find_concerns("app/models/concerns", "Model Concern", ActiveRecord::Base)
+      end
+
+      def find_controller_concerns
+        find_concerns("app/controllers/concerns", "Controller Concern", ActionController::Base)
+      end
+
+      def find_concerns(path, type, base_class)
+        return [] unless Dir.exist?(path)
+
+        Dir.glob("#{path}/**/*.rb").filter_map do |file|
+          class_name = file.gsub("#{path}/", "")
+                           .gsub(".rb", "")
+                           .camelize
+
+          concern = Object.const_get(class_name)
+          methods = concern.public_instance_methods(false).map(&:to_s).sort
+          included_in = find_included_in(concern, base_class)
+
+          { name: class_name, type: type, path: file, methods: methods, included_in: included_in }
+        rescue NameError
+          nil
+        end
+      end
+
+      def find_included_in(concern, base_class)
+        base_class.descendants
+                  .select { |klass| klass.ancestors.include?(concern) }
+                  .map(&:name)
+                  .compact
+                  .sort
+      end
+
+      def build_concern_lines(concern)
+        lines = []
+        lines << "#### #{concern[:name]}"
+        lines << "- Type: #{concern[:type]}"
+        lines << "- Location: #{concern[:path]}"
+        lines << if concern[:methods].any?
+                   "- Methods: #{concern[:methods].join(", ")}"
+                 else
+                   "- Methods: none"
+                 end
+        lines << if concern[:included_in].any?
+                   "- Included in: #{concern[:included_in].join(", ")}"
+                 else
+                   "- Included in: none detected"
+                 end
+        lines
+      end
+    end
+  end
+end

data/lib/docwright/extractors/database_extractor.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class DatabaseExtractor
+      def generate
+        skip = %w[schema_migrations ar_internal_metadata]
+        tables = ActiveRecord::Base.connection.tables.reject { |t| skip.include?(t) }.sort
+        lines = ["# Database Documentation\n"]
+
+        tables.each do |table|
+          lines << "## #{table}\n"
+          columns = ActiveRecord::Base.connection.columns(table)
+          columns.each do |col|
+            lines << "- **#{col.name}** (#{col.type})"
+          end
+
+          lines << ""
+        end
+
+        FileUtils.mkdir_p("docs")
+        Docwright::Merger.write("docs/database.md", lines.join("\n"))
+        puts "DocWright: Wrote docs/database.md"
+      end
+    end
+  end
+end

data/lib/docwright/extractors/model_extractor.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class ModelExtractor
+      def generate
+        models = find_models
+        FileUtils.mkdir_p("docs")
+
+        models.each do |model|
+          lines = []
+          lines << "## #{model.name}"
+          lines << "**Table:** #{model.table_name}\n"
+
+          lines << "### Associations"
+          associations = model.reflect_on_all_associations
+          if associations.empty?
+            lines << "- None"
+          else
+            associations.each do |a|
+              lines << "- #{a.macro} :#{a.name}"
+            end
+          end
+
+          lines << "\n### Validations"
+          validations = model.validators
+          if validations.empty?
+            lines << "- None"
+          else
+            validations.each do |v|
+              lines << "- #{v.class.name} on : #{v.attributes.join(", ")}"
+            end
+          end
+
+          notes = "### Notes for #{model.name}\n<!-- Add your notes about #{model.name} here -->"
+          Docwright::Merger.write_named("docs/models.md", model.name, lines.join("\n"), notes)
+        end
+
+        puts "DocWright: wrote docs/models.md"
+      end
+
+      private
+
+      def find_models
+        Rails.application.eager_load!
+        ActiveRecord::Base.descendants.reject { |m| m.abstract_class? }.sort_by(&:name)
+      end
+    end
+  end
+end

data/lib/docwright/extractors/services_extractor.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Extractors
+    class ServicesExtractor
+      def generate
+        Rails.application.eager_load!
+
+        services = find_services
+        if services.empty?
+          puts "DocWright: no services found — skipping services.md"
+          return
+        end
+
+        FileUtils.mkdir_p("docs")
+        services.each do |service|
+          lines = build_service_lines(service)
+          notes = "#### Notes for #{service[:name]}\n<!-- Describe when to use this service and what it does -->"
+          Docwright::Merger.write_named("docs/services.md", service[:name], lines.join("\n"), notes)
+        end
+
+        summary_lines = ["### Summary", "- Total services: #{services.size}"]
+        Docwright::Merger.write_named("docs/services.md", "_summary", summary_lines.join("\n"), "")
+
+        puts "DocWright: wrote docs/services.md"
+      end
+
+      private
+
+      def find_services # rubocop:disable Metrics/MethodLength
+        return [] unless Dir.exist?("app/services")
+
+        Dir.glob("app/services/**/*.rb").filter_map do |path|
+          class_name = path.gsub("app/services/", "")
+                           .gsub(".rb", "")
+                           .camelize
+
+          klass = Object.const_get(class_name)
+          methods = klass.public_instance_methods(false).map(&:to_s).sort
+
+          { name: class_name, path: path, methods: methods }
+        rescue NameError
+          nil
+        end
+      end
+
+      def build_service_lines(service)
+        lines = []
+        lines << "#### #{service[:name]}"
+        lines << "- Location: #{service[:path]}"
+        lines << if service[:methods].any?
+                   "- Public methods: #{service[:methods].join(", ")}"
+                 else
+                   "- Public methods: none"
+                 end
+        lines
+      end
+    end
+  end
+end

data/lib/docwright/generators/feature_generator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Docwright
+  module Generators
+    class FeatureGenerator
+      CONFIG_FILE = ".docwright.yml"
+
+      def generate
+        return unless File.exist?(CONFIG_FILE)
+
+        config = YAML.load_file(CONFIG_FILE)
+        features = config["features"] || []
+        return if features.empty?
+
+        FileUtils.mkdir_p("docs/features")
+
+        features.each do |feature|
+          name = feature["name"]
+          description = feature["description"]
+          path = "docs/features/#{name}.md"
+
+          if File.exist?(path)
+            puts "DocWright: skipped #{path} (already exists)"
+          else
+            File.write(path, template(name, description))
+            puts "DocWright: wrote #{path}"
+          end
+        end
+      end
+
+      private
+
+      def template(name, description)
+        <<~MD
+          # #{name.gsub("_", " ").capitalize}
+
+          #{description}
+
+          ## Overview
+          <!-- Describe this feature at a high level -->
+
+          ## Models involved
+          <!-- Auto-detection coming in a future phase -->
+
+          ## Controllers and actions
+          <!-- Auto-detection coming in a future phase -->
+
+          ## Services
+          <!-- Auto-detection coming in a future phase -->
+
+          ## Background jobs
+          <!-- Auto-detection coming in a future phase -->
+
+          ## Views
+          <!-- Auto-detection coming in a future phase -->
+
+          ## User flows
+
+          ### Happy path
+          <!-- Describe the main successful flow step by step -->
+          <!-- Example: User > sidebar > article list > click create > fill form > submit -->
+
+          ### Alternative paths
+          <!-- Describe edge cases, error states, or alternative routes -->
+
+          ## Edge cases
+          <!-- Document important edge cases for this feature -->
+        MD
+      end
+    end
+  end
+end