docwright 0.1.0

data/lib/docwright/generators/manual_generator.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Docwright
+  module Generators
+    class ManualGenerator
+      TEMPLATES = {
+        "overview.md" => <<~MD,
+          # Overview
+
+          ## What is this app?
+          <!-- Describe what this application does and why it exists -->
+
+          ## Who is it for?
+          <!-- Describe the target users or customers -->
+
+          ## Key features
+          <!-- List the main features of the application -->
+        MD
+        "business_rules.md" => <<~MD,
+          # Business Rules
+
+          ## Core rules
+          <!-- Describe the fundamental business rules that drive this application -->
+
+          ## Edge cases
+          <!-- Document important edge cases and how they are handled -->
+        MD
+        "setup.md" => <<~MD,
+          # Setup
+
+          ## Requirements
+          <!-- List required tools, languages, and versions -->
+
+          ## Installation
+          <!-- Step by step setup instructions -->
+
+          ## Environment variables
+          <!-- List all required environment variables and what they do -->
+
+          ## Seed data
+          <!-- Describe seed data and how to run it -->
+        MD
+        "architecture.md" => <<~MD,
+          # Architecture
+
+          ## High-level structure
+          <!-- Describe the overall structure of the application -->
+
+          ## Key design decisions
+          <!-- Document important architectural decisions and the reasoning behind them -->
+
+          ## External dependencies
+          <!-- List external services, APIs, or libraries this app depends on -->
+        MD
+        "deployment.md" => <<~MD,
+          # Deployment
+
+          ## Environments
+          <!-- List all environments and their purposes -->
+
+          ## Deploy process
+          <!-- Step by step deployment instructions -->
+
+          ## Infrastructure
+          <!-- Describe the infrastructure this app runs on -->
+        MD
+        "security.md" => <<~MD,
+          # Security
+
+          ## Authentication
+          <!-- Describe how authentication works -->
+
+          ## Authorization
+          <!-- Describe how authorization and permissions work -->
+
+          ## Sensitive data
+          <!-- List sensitive data this app handles and how it is protected -->
+        MD
+        "troubleshooting.md" => <<~MD,
+          # Troubleshooting
+
+          ## Common problems
+          <!-- List common issues and their solutions -->
+
+          ## Debugging tips
+          <!-- Useful tips for debugging this application -->
+        MD
+        "changelog.md" => <<~MD,
+          # Changelog
+
+          ## Unreleased
+          <!-- Changes not yet in production -->
+
+          ## [Version] - YYYY-MM-DD
+          <!-- Document significant changes per release -->
+        MD
+        "readme.md" => <<~MD
+          # [App Name]
+
+          ## Overview
+          <!-- Brief description of the application -->
+
+          ## Quick start
+          <!-- Fastest way to get the app running locally -->
+
+          ## Documentation
+          <!-- Link to or summarize key documentation -->
+        MD
+      }.freeze
+
+      def generate
+        FileUtils.mkdir_p("docs")
+        TEMPLATES.each do |filename, content|
+          path = "docs/#{filename}"
+          if File.exist?(path)
+            puts "DocWright: skipped #{path} (already exists)"
+          else
+            File.write(path, content)
+            puts "DocWright: wrote #{path}"
+          end
+        end
+      end
+
+      def generate_single(path, filename)
+        return if File.exist?(path)
+
+        content = TEMPLATES[filename]
+        return unless content
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+      end
+    end
+  end
+end

data/lib/docwright/merger.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Docwright
+  class Merger
+    AUTO_START = "<!-- DOCWRIGHT:AUTO -->"
+    AUTO_END = "<!-- DOCWRIGHT:END -->"
+
+    def self.write(path, auto_content)
+      if File.exist?(path)
+        merge(path, auto_content)
+      else
+        fresh(path, auto_content)
+      end
+    end
+
+    def self.write_named(path, name, auto_content, notes_placeholder)
+      if File.exist?(path)
+        merge_named(path, name, auto_content)
+      else
+        fresh_named(path, name, auto_content, notes_placeholder)
+      end
+    end
+
+    def self.fresh(path, auto_content)
+      content = "#{AUTO_START}\n#{auto_content}\n#{AUTO_END}"
+      File.write(path, content)
+    end
+
+    def self.fresh_named(path, name, auto_content, notes_placeholder)
+      content = ""
+      content += "<!-- DOCWRIGHT:AUTO:#{name} -->\n"
+      content += "#{auto_content}\n"
+      content += "<!-- DOCWRIGHT:END:#{name} -->\n"
+      content += "#{notes_placeholder}\n"
+      File.write(path, content)
+    end
+
+    def self.merge(path, auto_content)
+      existing = File.read(path)
+      replacement = "#{AUTO_START}\n#{auto_content}\n#{AUTO_END}"
+      updated = existing.gsub(/#{Regexp.escape(AUTO_START)}.*?#{Regexp.escape(AUTO_END)}/m, replacement)
+      File.write(path, updated)
+    end
+
+    def self.merge_named(path, name, auto_content)
+      existing = File.read(path)
+      start_marker = "<!-- DOCWRIGHT:AUTO:#{name} -->"
+      end_marker = "<!-- DOCWRIGHT:END:#{name} -->"
+      replacement = "#{start_marker}\n#{auto_content}\n#{end_marker}"
+
+      updated = if existing.include?(start_marker)
+                  existing.gsub(/#{Regexp.escape(start_marker)}.*?#{Regexp.escape(end_marker)}/m, replacement)
+                else
+                  existing + "\n#{replacement}\n### Notes for #{name}\n<!-- Add your notes about #{name} here -->\n"
+                end
+      File.write(path, updated)
+    end
+  end
+end

data/lib/docwright/railtie.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Docwright
+  # Railtie for integrating Docwright with Rails.
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      load File.expand_path("tasks/docwright.rake", __dir__)
+    end
+  end
+end

data/lib/docwright/searcher.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Docwright
+  class Searcher
+    def initialize(term)
+      @term = term
+    end
+
+    def run
+      puts "\nDocWright Search: \"#{@term}\""
+      puts "===================================\n\n"
+
+      results = search_docs
+      print_results(results)
+    end
+
+    private
+
+    def search_docs
+      md_files = Dir.glob("docs/**/*.md")
+      results = {}
+
+      md_files.each do |file|
+        matches = []
+        File.readlines(file).each_with_index do |line, i|
+          matches << { line_number: i + 1, content: line.chomp } if line.downcase.include?(@term.downcase)
+        end
+
+        results[file] = matches if matches.any?
+      end
+
+      results
+    end
+
+    def print_results(results)
+      if results.empty?
+        puts "No matches found for \"#{@term}\""
+        return
+      end
+
+      total_matches = 0
+
+      results.each do |file, matches|
+        puts file
+        matches.each do |match|
+          puts "Line #{match[:line_number]}: #{match[:content].strip}"
+          total_matches += 1
+        end
+        puts ""
+      end
+
+      puts "#{results.size} #{"file".pluralize(results.size)}, #{total_matches} #{"match".pluralize(total_matches)} found."
+    end
+  end
+end

data/lib/docwright/tasks/docwright.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :docwright do
+  desc "Generate documentation for this Rails application"
+  task generate: :environment do
+    # Docwright::Extractors::DatabaseExtractor.new.generate
+    # Docwright::Extractors::ApiExtractor.new.generate
+    # Docwright::Extractors::ModelExtractor.new.generate
+    # Docwright::Generators::ManualGenerator.new.generate
+    # Docwright::Generators::FeatureGenerator.new.generate
+    Docwright::Wizard.new.run
+  end
+
+  desc "Check Documentation completeness"
+  task check: :environment do
+    Docwright::Checker.new.run
+  end
+
+  desc "Search documentation"
+  task :search, [:term] => :environment do |_, args|
+    term = args[:term]
+    if term.nil? || term.empty?
+      puts "Usage: rake docwright:search[your_search_term]"
+    else
+      Docwright::Searcher.new(term).run
+    end
+  end
+end

data/lib/docwright/version.rb

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

data/lib/docwright/wizard.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Docwright
+  class Wizard # rubocop:disable Metrics/ClassLength
+    FIRST_RUN_MESSAGE = <<~MSG
+      ============================================
+      DocWright — Rails Documentation Generator
+      ============================================
+
+      This tool will generate a docs/ folder with:
+
+        Auto-generated (safe to regenerate anytime):
+          - database.md   — tables, columns, types
+          - api.md        — routes and endpoints
+          - models.md     — model associations and validations
+
+        Manual templates (written once, never overwritten):
+          - overview.md, setup.md, architecture.md,
+            deployment.md, security.md, troubleshooting.md,
+            business_rules.md, changelog.md, readme.md
+          - docs/features/ — feature-specific docs
+
+        Important:
+          Never manually edit content inside
+          <!-- DOCWRIGHT:AUTO --> blocks — it will be overwritten.
+          Write your notes outside those markers.
+
+      ============================================
+    MSG
+
+    DOCWRIGHT_YML_TEMPLATE = <<~YAML
+      # DocWright feature configuration
+      # Declare your app's features here and DocWright will generate a doc template for each one.
+      ##{" "}
+      # Optional narrative docs - set to true to generate
+      # DocWright will only generate these if the relevant folders exist in your app
+      ##{" "}
+      # optional_docs:
+      #   controllers: true
+      #   background_jobs: true
+      #   services: true
+      #   auth_and_permissions: true
+      #
+      # Feature-specific docs
+      # Uncomment and edit the example below to add your features:
+      #
+      # features:
+      #   - name: qr_flow
+      #     description: QR code generation and scanning flow
+      #   - name: subscriptions
+      #     description: Billing, plan management, and renewals
+    YAML
+
+    def run # rubocop:disable Metrics/MethodLength
+      ## File.exist? also works for both files and directories but Dir.exist? is specific for folder and return nil if that is named as file name
+      first_run = !Dir.exist?("docs")
+      puts FIRST_RUN_MESSAGE if first_run
+
+      create_config_if_missing
+
+      puts "\nDocWright: scanning your app...\n\n"
+
+      report = detection_pass
+      display_report(report)
+
+      return unless confirm
+
+      generate_auto_files
+      process_manual_files(report[:new_manual])
+      process_manual_files(report[:new_features])
+
+      puts "\nDocWright: done!\n"
+    rescue Interrupt
+      puts "\n\nDocWright: wizard cancelled."
+    end
+
+    private
+
+    def create_config_if_missing
+      return if File.exist?(".docwright.yml")
+
+      File.write(".docwright.yml", DOCWRIGHT_YML_TEMPLATE)
+      puts "DocWright: created .docwright.yml — add your features there.\n"
+    end
+
+    def detection_pass # rubocop:disable Metrics/MethodLength
+      auto_files = %w[database.md api.md models.md]
+      manual_files = %w[overview.md business_rules.md setup.md
+                        architecture.md deployment.md security.md
+                        troubleshooting.md changelog.md readme.md]
+
+      feature_files = load_feature_files
+      {
+        auto: auto_files,
+        new_manual: manual_files.reject { |f| File.exist?("docs/#{f}") },
+        existing_manual: manual_files.select { |f| File.exist?("docs/#{f}") },
+        new_features: feature_files.reject { |f| File.exist?("docs/features/#{f}") },
+        existing_features: feature_files.select { |f| File.exist?("docs/features/#{f}") }
+      }
+    end
+
+    def load_feature_files
+      return [] unless File.exist?(".docwright.yml")
+
+      require "yaml"
+      config = YAML.load_file(".docwright.yml")
+      return [] unless config.is_a?(Hash)
+
+      (config["features"] || []).map { |f| "#{f["name"]}.md" }
+    end
+
+    def display_report(report) # rubocop:disable Metrics/CyclomaticComplexity
+      puts "  Will regenerate (auto):"
+      report[:auto].each { |f| puts "    - #{f}" }
+
+      unless report[:new_manual].empty?
+        puts "\n  Will generate (new manual templates):"
+        report[:new_manual].each { |f| puts "    - #{f}" }
+      end
+
+      unless report[:new_features].empty?
+        puts "\n  Will generate (new feature docs):"
+        report[:new_features].each { |f| puts "    - #{f}" }
+      end
+
+      unless report[:existing_manual].empty?
+        puts "\n  Will skip (already exist):"
+        report[:existing_manual].each { |f| puts "    - #{f}" }
+      end
+
+      return if report[:existing_features].empty?
+
+      puts "\n  Will skip (already exist):"
+      report[:existing_features].each { |f| puts "    - #{f}" }
+    end
+
+    def confirm
+      print "\nContinue? (y/n): "
+      $stdin.gets.chomp.downcase == "y"
+    end
+
+    def generate_auto_files
+      puts "\nDocWright: generating auto files..."
+      Docwright::Extractors::DatabaseExtractor.new.generate
+      Docwright::Extractors::ApiExtractor.new.generate
+      Docwright::Extractors::ModelExtractor.new.generate
+      generate_optional_docs
+    end
+
+    def generate_optional_docs
+      return unless File.exist?(".docwright.yml")
+
+      require "yaml"
+      config = YAML.load_file(".docwright.yml")
+      return unless config.is_a?(Hash)
+
+      optional = config["optional_docs"] || {}
+      Docwright::Extractors::AuthExtractor.new.generate if optional["auth_and_permissions"]
+      Docwright::Extractors::BackgroundJobsExtractor.new.generate if optional["background_jobs"]
+      Docwright::Extractors::ServicesExtractor.new.generate if optional["services"]
+      Docwright::Extractors::ConcernsExtractor.new.generate if optional["concerns"]
+    end
+
+    def process_manual_files(files)
+      return if files.empty?
+
+      files.each do |filename|
+        feature = !%w[overview.md business_rules.md setup.md
+                      architecture.md deployment.md security.md
+                      troubleshooting.md changelog.md readme.md].include?(filename)
+
+        path = feature ? "docs/features/#{filename}" : "docs/#{filename}"
+
+        loop do
+          puts "\nGenerate #{filename}?"
+          puts "  [w] write in terminal"
+          puts "  [e] open in $EDITOR"
+          puts "  [s] skip for now"
+          puts "  [q] quit wizard"
+          print "Choice: "
+
+          case $stdin.gets.chomp.downcase
+          when "w"
+            write_in_terminal(path)
+            break
+          when "e"
+            open_in_editor(path)
+            break
+          when "s"
+            write_template(path, filename)
+            puts "DocWright: skipped #{filename} — template saved, fill it in later"
+            break
+          when "q"
+            puts "DocWright: wizard exited."
+            return
+          else
+            puts "Invalid choice. Please enter w, e, s, or q."
+          end
+        end
+      end
+    end
+
+    def write_in_terminal(path)
+      puts "Type your content. Type 'END' on a new line when done (or Ctrl+C to cancel):"
+
+      lines = []
+      begin
+        loop do
+          line = $stdin.gets.chomp
+          break if line == "END"
+          break if %w[exit q].include?(line.downcase)
+
+          lines << line
+        end
+      rescue Interrupt
+        puts "\nCancelled."
+        return
+      end
+
+      if lines.empty?
+        puts "DocWright: nothing written, skipping #{path}"
+        return
+      end
+
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, lines.join("\n"))
+      puts "DocWright: wrote #{path}"
+    end
+
+    def open_in_editor(path)
+      FileUtils.mkdir_p(File.dirname(path))
+      write_template(path, File.basename(path))
+      editor = ENV["EDITOR"] || "nano"
+      system("#{editor} #{path}")
+      puts "DocWright: wrote #{path}"
+    end
+
+    def write_template(path, filename)
+      FileUtils.mkdir_p(File.dirname(path))
+      Docwright::Generators::ManualGenerator.new.generate_single(path, filename)
+    end
+  end
+end

data/lib/docwright.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "docwright/version"
+require "rails/railtie"
+require_relative "docwright/railtie"
+require_relative "docwright/merger"
+require_relative "docwright/extractors/database_extractor"
+require_relative "docwright/extractors/api_extractor"
+require_relative "docwright/extractors/model_extractor"
+require_relative "docwright/extractors/auth_extractor"
+require_relative "docwright/extractors/background_jobs_extractor"
+require_relative "docwright/extractors/services_extractor"
+require_relative "docwright/extractors/concerns_extractor"
+require_relative "docwright/generators/manual_generator"
+require_relative "docwright/generators/feature_generator"
+require_relative "docwright/wizard"
+require_relative "docwright/checker"
+require_relative "docwright/searcher"
+
+module Docwright
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/docwright.rbs

@@ -0,0 +1,4 @@
+module Docwright
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: docwright
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Grace
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: DocWright introspects your live Rails app to generate structured markdown
+  documentation for your database schema, API routes, models, services, background
+  jobs, and more. Human-written content is preserved across regenerations using smart
+  merge markers.
+email:
+- thirihtethtetaung.dev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- examples/.docwright.yml
+- examples/README.md
+- examples/api.md
+- examples/concerns.md
+- examples/database.md
+- examples/models.md
+- lib/docwright.rb
+- lib/docwright/checker.rb
+- lib/docwright/extractors/api_extractor.rb
+- lib/docwright/extractors/auth_extractor.rb
+- lib/docwright/extractors/background_jobs_extractor.rb
+- lib/docwright/extractors/concerns_extractor.rb
+- lib/docwright/extractors/database_extractor.rb
+- lib/docwright/extractors/model_extractor.rb
+- lib/docwright/extractors/services_extractor.rb
+- lib/docwright/generators/feature_generator.rb
+- lib/docwright/generators/manual_generator.rb
+- lib/docwright/merger.rb
+- lib/docwright/railtie.rb
+- lib/docwright/searcher.rb
+- lib/docwright/tasks/docwright.rake
+- lib/docwright/version.rb
+- lib/docwright/wizard.rb
+- sig/docwright.rbs
+homepage: https://github.com/GraceHtet/docwright
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/GraceHtet/docwright
+  source_code_uri: https://github.com/GraceHtet/docwright
+  changelog_uri: https://github.com/GraceHtet/docwright/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Auto-generate and maintain documentation for your Rails application
+test_files: []