docyard 0.9.0 → 1.0.0

data/lib/docyard/search/dev_indexer.rb

@@ -3,13 +3,17 @@
 require "fileutils"
 require "tmpdir"
 require "open3"
+require "parallel"
 require "tty-progressbar"
+require_relative "../utils/path_utils"
 
 module Docyard
   module Search
     class DevIndexer
       include PagefindSupport
 
+      PARALLEL_THRESHOLD = 10
+
       attr_reader :docs_path, :config, :temp_dir, :pagefind_path
 
       def initialize(docs_path:, config:)
@@ -26,12 +30,12 @@ module Docyard
         @temp_dir = Dir.mktmpdir("docyard-search-")
         generate_html_files
         page_count = run_pagefind
-        @pagefind_path = File.join(temp_dir, "pagefind")
+        @pagefind_path = File.join(temp_dir, "_docyard", "pagefind")
 
         log_success(page_count)
         pagefind_path
       rescue StandardError => e
-        warn "[!] Search index generation failed: #{e.message}"
+        Docyard.logger.warn("Search index generation failed: #{e.message}")
         cleanup
         nil
       end
@@ -46,7 +50,7 @@ module Docyard
 
       def pagefind_available?
         result = super
-        warn "[!] Search disabled: Pagefind not found (npm install -g pagefind)" unless result
+        Docyard.logger.warn("Search disabled: Pagefind not found (npm install -g pagefind)") unless result
         result
       end
 
@@ -54,20 +58,43 @@ module Docyard
         markdown_files = Dir.glob(File.join(docs_path, "**", "*.md"))
         markdown_files = filter_excluded_files(markdown_files)
         markdown_files = filter_non_indexable_files(markdown_files)
-        renderer = Renderer.new(base_url: "/", config: config)
 
         progress = TTY::ProgressBar.new(
           "Indexing search [:bar] :current/:total (:percent)",
           total: markdown_files.size,
           width: 50
         )
+        mutex = Mutex.new
+
+        Logging.start_buffering
+        if markdown_files.size >= PARALLEL_THRESHOLD
+          generate_files_in_parallel(markdown_files, progress, mutex)
+        else
+          generate_files_sequentially(markdown_files, progress)
+        end
+        Logging.flush_warnings
+      end
 
+      def generate_files_in_parallel(markdown_files, progress, mutex)
+        Parallel.each(markdown_files, in_threads: Parallel.processor_count) do |file_path|
+          renderer = thread_local_renderer
+          generate_html_file(file_path, renderer)
+          mutex.synchronize { progress.advance }
+        end
+      end
+
+      def generate_files_sequentially(markdown_files, progress)
+        renderer = Renderer.new(base_url: "/", config: config)
         markdown_files.each do |file_path|
           generate_html_file(file_path, renderer)
           progress.advance
         end
       end
 
+      def thread_local_renderer
+        Thread.current[:docyard_search_renderer] ||= Renderer.new(base_url: "/", config: config)
+      end
+
       def filter_excluded_files(files)
         exclude_patterns = config.search.exclude || []
         return files if exclude_patterns.empty?
@@ -96,40 +123,21 @@ module Docyard
       end
 
       def file_to_url_path(file_path)
-        relative_path = file_path.delete_prefix("#{docs_path}/")
-        base_name = File.basename(relative_path, ".md")
-        dir_name = File.dirname(relative_path)
-
-        if base_name == "index"
-          dir_name == "." ? "/" : "/#{dir_name}"
-        else
-          dir_name == "." ? "/#{base_name}" : "/#{dir_name}/#{base_name}"
-        end
+        Utils::PathUtils.markdown_file_to_url(file_path, docs_path)
       end
 
       def generate_html_file(markdown_file, renderer)
         relative_path = markdown_file.delete_prefix("#{docs_path}/")
         output_path = determine_output_path(relative_path)
 
-        html = renderer.render_file(markdown_file, branding: branding_options)
+        html = renderer.render_for_search(markdown_file)
 
         FileUtils.mkdir_p(File.dirname(output_path))
         File.write(output_path, html)
       end
 
       def determine_output_path(relative_path)
-        base_name = File.basename(relative_path, ".md")
-        dir_name = File.dirname(relative_path)
-
-        if base_name == "index"
-          File.join(temp_dir, dir_name, "index.html")
-        else
-          File.join(temp_dir, dir_name, base_name, "index.html")
-        end
-      end
-
-      def branding_options
-        BrandingResolver.new(config).resolve
+        Utils::PathUtils.markdown_to_html_output(relative_path, temp_dir)
       end
 
       def run_pagefind
@@ -147,8 +155,8 @@ module Docyard
       end
 
       def log_success(page_count)
-        puts "=> Search index generated (#{page_count} pages indexed)"
-        puts "=> Temp directory: #{temp_dir}" if ENV["DOCYARD_DEBUG"]
+        Docyard.logger.info("* Search index generated (#{page_count} pages indexed)")
+        Docyard.logger.debug("* Temp directory: #{temp_dir}")
       end
     end
   end

data/lib/docyard/search/pagefind_support.rb

@@ -17,7 +17,7 @@ module Docyard
       end
 
       def build_pagefind_args(site_dir)
-        args = ["pagefind", "--site", site_dir]
+        args = ["pagefind", "--site", site_dir, "--output-subdir", "_docyard/pagefind"]
 
         exclusions = config.search.exclude || []
         exclusions.each do |pattern|

data/lib/docyard/server/asset_handler.rb

@@ -1,8 +1,15 @@
 # frozen_string_literal: true
 
+require "digest"
+require_relative "../utils/path_utils"
+
 module Docyard
   class AssetHandler
     TEMPLATES_ASSETS_PATH = File.join(__dir__, "../templates", "assets")
+    CACHE_MAX_AGE = 3600
+    DEFAULT_PUBLIC_DIR = "docs/public"
+
+    attr_reader :public_dir
 
     CONTENT_TYPES = {
       ".css" => "text/css; charset=utf-8",
@@ -23,47 +30,52 @@ module Docyard
       ".webm" => "video/webm"
     }.freeze
 
-    def serve_docyard_assets(request_path)
-      asset_path = request_path.delete_prefix("/_docyard/")
+    def initialize(public_dir: DEFAULT_PUBLIC_DIR)
+      @public_dir = public_dir
+    end
 
-      return forbidden_response if directory_traversal?(asset_path)
+    def serve_docyard_assets(request_path)
+      asset_path = Utils::PathUtils.decode_path(request_path.delete_prefix("/_docyard/"))
 
       return serve_components_css if asset_path == "css/components.css"
       return serve_components_js if asset_path == "js/components.js"
 
-      file_path = File.join(TEMPLATES_ASSETS_PATH, asset_path)
+      file_path = safe_asset_path(asset_path, TEMPLATES_ASSETS_PATH)
+      return forbidden_response unless file_path
       return not_found_response unless File.file?(file_path)
 
       serve_file(file_path)
     end
 
     def serve_public_file(request_path)
-      asset_path = request_path.delete_prefix("/")
+      asset_path = Utils::PathUtils.decode_path(request_path.delete_prefix("/"))
 
-      return nil if directory_traversal?(asset_path)
-
-      file_path = File.join(Constants::PUBLIC_DIR, asset_path)
-      return nil unless File.file?(file_path)
+      file_path = safe_asset_path(asset_path, public_dir)
+      return nil unless file_path && File.file?(file_path)
 
       serve_file(file_path)
     end
 
     private
 
-    def directory_traversal?(path)
-      path.include?("..")
+    def safe_asset_path(relative_path, base_dir)
+      Utils::PathUtils.resolve_safe_path(relative_path, base_dir)
     end
 
     def serve_file(file_path)
       content = File.read(file_path)
-      content_type = detect_content_type(file_path)
+      headers = build_cache_headers(content, File.mtime(file_path))
+      headers["Content-Type"] = detect_content_type(file_path)
 
-      [200, { "Content-Type" => content_type }, [content]]
+      [200, headers, [content]]
     end
 
     def serve_components_css
       content = concatenate_component_css
-      [200, { "Content-Type" => "text/css; charset=utf-8" }, [content]]
+      headers = build_cache_headers(content)
+      headers["Content-Type"] = "text/css; charset=utf-8"
+
+      [200, headers, [content]]
     end
 
     def concatenate_component_css
@@ -76,7 +88,10 @@ module Docyard
 
     def serve_components_js
       content = concatenate_component_js
-      [200, { "Content-Type" => "application/javascript; charset=utf-8" }, [content]]
+      headers = build_cache_headers(content)
+      headers["Content-Type"] = "application/javascript; charset=utf-8"
+
+      [200, headers, [content]]
     end
 
     def concatenate_component_js
@@ -92,6 +107,15 @@ module Docyard
       CONTENT_TYPES.fetch(extension, "application/octet-stream")
     end
 
+    def build_cache_headers(content, last_modified = nil)
+      headers = {
+        "Cache-Control" => "public, max-age=#{CACHE_MAX_AGE}",
+        "ETag" => %("#{Digest::MD5.hexdigest(content)}")
+      }
+      headers["Last-Modified"] = last_modified.httpdate if last_modified
+      headers
+    end
+
     def forbidden_response
       [403, { "Content-Type" => "text/plain" }, ["403 Forbidden"]]
     end

data/lib/docyard/server/dev_server.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
-require "webrick"
-require "stringio"
-require_relative "file_watcher"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require "puma/log_writer"
 require_relative "rack_application"
+require_relative "sse_server"
+require_relative "file_watcher"
 require_relative "../config"
+require_relative "../navigation/sidebar/cache"
 
 module Docyard
-  class Server
+  class DevServer
     DEFAULT_PORT = 4200
     DEFAULT_HOST = "localhost"
 
@@ -19,27 +23,34 @@ module Docyard
       @docs_path = docs_path
       @search_enabled = search
       @config = Config.load
-      @file_watcher = FileWatcher.new(File.expand_path(docs_path))
       @search_indexer = nil
-      @app = nil
+      @sse_server = nil
+      @file_watcher = nil
+      @launcher = nil
+      @sidebar_cache = nil
     end
 
     def start
       validate_docs_directory!
+      build_sidebar_cache
       generate_search_index if @search_enabled
-      initialize_app
+      setup_hot_reload
       print_server_info
-      @file_watcher.start
-
-      http_server.mount_proc("/") { |req, res| handle_request(req, res) }
-      trap("INT") { shutdown_server }
-
-      http_server.start
+      run_server
+    ensure
       cleanup
     end
 
     private
 
+    def build_sidebar_cache
+      @sidebar_cache = Sidebar::Cache.new(
+        docs_path: File.expand_path(docs_path),
+        config: @config
+      )
+      @sidebar_cache.build
+    end
+
     def generate_search_index
       @search_indexer = Search::DevIndexer.new(
         docs_path: File.expand_path(docs_path),
@@ -48,17 +59,45 @@ module Docyard
       @search_indexer.generate
     end
 
-    def initialize_app
-      @app = RackApplication.new(
-        docs_path: File.expand_path(docs_path),
-        file_watcher: @file_watcher,
-        config: @config,
-        pagefind_path: @search_indexer&.pagefind_path
+    def setup_hot_reload
+      @sse_server = SSEServer.new(port: sse_port)
+      @sse_server.start
+
+      @file_watcher = FileWatcher.new(
+        docs_path: docs_path,
+        on_change: ->(change_type) { handle_file_change(change_type) }
       )
+      @file_watcher.start
+    end
+
+    def sse_port
+      port + 1
+    end
+
+    def handle_file_change(change_type)
+      invalidate_sidebar_cache if change_type == :full
+      log_file_change(change_type)
+      @sse_server.broadcast("reload", { type: change_type.to_s })
+    end
+
+    def invalidate_sidebar_cache
+      @sidebar_cache&.invalidate
+      @sidebar_cache&.build
+    end
+
+    def log_file_change(change_type)
+      message = case change_type
+                when :content then "Content changed, reloading..."
+                when :config then "Config changed, full reload..."
+                when :asset then "Asset changed, reloading..."
+                else "File changed, reloading..."
+                end
+      Docyard.logger.info("* #{message}")
     end
 
     def cleanup
-      @file_watcher.stop
+      @file_watcher&.stop
+      @sse_server&.stop
       @search_indexer&.cleanup
     end
 
@@ -70,48 +109,44 @@ module Docyard
     end
 
     def print_server_info
-      puts "Starting Docyard server..."
-      puts "=> Serving docs from: #{docs_path}/"
-      puts "=> Running at: http://#{host}:#{port}"
-      puts "=> Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}"
-      puts "=> Press Ctrl+C to stop\n"
+      Docyard.logger.info("Starting Docyard server...")
+      Docyard.logger.info("* Version: #{Docyard::VERSION}")
+      Docyard.logger.info("* Running at: http://#{host}:#{port}")
+      Docyard.logger.info("* Hot reload: ws://127.0.0.1:#{sse_port}")
+      Docyard.logger.info("* Search: #{@search_enabled ? 'enabled' : 'disabled (use --search to enable)'}")
+      Docyard.logger.info("Use Ctrl+C to stop\n")
     end
 
-    def shutdown_server
-      puts "\nShutting down server..."
-      http_server.shutdown
-    end
+    def run_server
+      app = build_rack_app
+      puma_config = build_puma_config(app)
+      log_writer = Puma::LogWriter.strings
 
-    def http_server
-      @http_server ||= WEBrick::HTTPServer.new(
-        Port: port,
-        BindAddress: host,
-        AccessLog: [],
-        Logger: WEBrick::Log.new(File::NULL)
-      )
+      @launcher = Puma::Launcher.new(puma_config, log_writer: log_writer)
+      @launcher.run
     end
 
-    def handle_request(req, res)
-      env = build_rack_env(req)
-      status, headers, body = @app.call(env)
-
-      res.status = status
-      headers.each { |key, value| res[key] = value }
-      body.each { |chunk| res.body << chunk }
+    def build_rack_app
+      RackApplication.new(
+        docs_path: File.expand_path(docs_path),
+        config: @config,
+        pagefind_path: @search_indexer&.pagefind_path,
+        sse_port: sse_port,
+        sidebar_cache: @sidebar_cache
+      )
     end
 
-    def build_rack_env(req)
-      {
-        "REQUEST_METHOD" => req.request_method,
-        "PATH_INFO" => req.path,
-        "QUERY_STRING" => req.query_string || "",
-        "SERVER_NAME" => req.host,
-        "SERVER_PORT" => req.port.to_s,
-        "rack.version" => Rack::VERSION,
-        "rack.url_scheme" => "http",
-        "rack.input" => StringIO.new,
-        "rack.errors" => $stderr
-      }
+    def build_puma_config(app)
+      server_host = host
+      server_port = port
+
+      Puma::Configuration.new do |config|
+        config.bind "tcp://#{server_host}:#{server_port}"
+        config.app app
+        config.workers 0
+        config.threads 4, 8
+        config.quiet
+      end
     end
   end
 end

data/lib/docyard/server/file_watcher.rb

@@ -4,39 +4,89 @@ require "listen"
 
 module Docyard
   class FileWatcher
-    attr_reader :last_modified_time
+    DEBOUNCE_DELAY = 0.1
+    ROOT_CONFIG_FILE = "docyard.yml"
+    CONFIG_FILES = %w[docyard.yml _sidebar.yml].freeze
+    CONTENT_EXTENSIONS = %w[.md .markdown].freeze
+    ASSET_EXTENSIONS = %w[.css .js .html .erb].freeze
 
-    def initialize(docs_path)
-      @docs_path = docs_path
-      @last_modified_time = Time.now
-      @listener = nil
+    def initialize(docs_path:, on_change:)
+      @docs_path = File.expand_path(docs_path)
+      @project_root = File.dirname(@docs_path)
+      @on_change = on_change
+      @docs_listener = nil
+      @config_listener = nil
+      @pending_changes = { content: false, config: false, asset: false }
+      @debounce_timer = nil
+      @mutex = Mutex.new
     end
 
     def start
-      @listener = Listen.to(@docs_path, only: /\.md$/) do |modified, added, removed|
-        handle_changes(modified, added, removed)
+      @docs_listener = Listen.to(@docs_path, latency: DEBOUNCE_DELAY) do |modified, added, removed|
+        handle_changes(modified + added + removed)
       end
+      @docs_listener.start
 
-      @listener.start
+      @config_listener = Listen.to(@project_root, only: /\Adocyard\.yml\z/) do |modified, added, removed|
+        handle_changes(modified + added + removed)
+      end
+      @config_listener.start
     end
 
     def stop
-      @listener&.stop
-    rescue StandardError => e
-      Docyard.logger.error "Error stopping file watcher: #{e.class} - #{e.message}"
+      @docs_listener&.stop
+      @config_listener&.stop
+      @debounce_timer&.kill
     end
 
-    def changed_since?(timestamp)
-      @last_modified_time > timestamp
+    private
+
+    def handle_changes(paths)
+      return if paths.empty?
+
+      @mutex.synchronize do
+        paths.each { |path| categorize_change(path) }
+        schedule_notification
+      end
     end
 
-    private
+    def categorize_change(path)
+      filename = File.basename(path)
+
+      if CONFIG_FILES.include?(filename)
+        @pending_changes[:config] = true
+      elsif CONTENT_EXTENSIONS.include?(File.extname(path))
+        @pending_changes[:content] = true
+      elsif ASSET_EXTENSIONS.include?(File.extname(path))
+        @pending_changes[:asset] = true
+      end
+    end
+
+    def schedule_notification
+      @debounce_timer&.kill
+      @debounce_timer = Thread.new do
+        sleep DEBOUNCE_DELAY
+        send_notification
+      end
+    end
+
+    def send_notification
+      changes = nil
+      @mutex.synchronize do
+        changes = @pending_changes.dup
+        @pending_changes = { content: false, config: false, asset: false }
+      end
+
+      change_type = determine_change_type(changes)
+      @on_change.call(change_type) if change_type
+    end
 
-    def handle_changes(modified, added, removed)
-      return if modified.empty? && added.empty? && removed.empty?
+    def determine_change_type(changes)
+      return :full if changes[:config]
+      return :content if changes[:content]
+      return :asset if changes[:asset]
 
-      @last_modified_time = Time.now
-      Docyard.logger.info "Files changed, triggering reload..."
+      nil
     end
   end
 end

data/lib/docyard/server/pagefind_handler.rb

@@ -31,7 +31,7 @@ module Docyard
       return File.join(pagefind_path, relative_path) if pagefind_path && Dir.exist?(pagefind_path)
 
       output_dir = config&.build&.output_dir || "dist"
-      File.join(output_dir, "pagefind", relative_path)
+      File.join(output_dir, "_docyard", "pagefind", relative_path)
     end
 
     def serve_file(file_path)

data/lib/docyard/server/preview_server.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
 
-require "webrick"
+require "puma"
+require "puma/configuration"
+require "puma/launcher"
+require "puma/log_writer"
 require_relative "../config"
+require_relative "static_file_app"
 
 module Docyard
   class PreviewServer
@@ -13,16 +17,13 @@ module Docyard
       @port = port
       @config = Config.load
       @output_dir = File.expand_path(@config.build.output)
+      @launcher = nil
     end
 
     def start
       validate_output_directory!
       print_server_info
-
-      server = create_server
-      trap("INT") { shutdown_server(server) }
-
-      server.start
+      run_server
     end
 
     private
@@ -35,38 +36,33 @@ module Docyard
     end
 
     def print_server_info
-      puts "Preview server starting..."
-      puts "=> Serving from: #{output_dir}/"
-      puts "=> Running at: http://localhost:#{port}"
-      puts "=> Press Ctrl+C to stop\n"
+      Docyard.logger.info("Starting preview server...")
+      Docyard.logger.info("* Version: #{Docyard::VERSION}")
+      Docyard.logger.info("* Running at: http://localhost:#{port}")
+      Docyard.logger.info("Use Ctrl+C to stop\n")
     end
 
-    def create_server
-      WEBrick::HTTPServer.new(
-        Port: port,
-        DocumentRoot: output_dir,
-        AccessLog: [],
-        Logger: WEBrick::Log.new(File::NULL),
-        MimeTypes: mime_types
-      )
-    end
+    def run_server
+      app = StaticFileApp.new(output_dir)
+      puma_config = build_puma_config(app)
+      log_writer = Puma::LogWriter.strings
 
-    def mime_types
-      WEBrick::HTTPUtils::DefaultMimeTypes.merge(
-        {
-          "css" => "text/css",
-          "js" => "application/javascript",
-          "json" => "application/json",
-          "svg" => "image/svg+xml",
-          "woff" => "font/woff",
-          "woff2" => "font/woff2"
-        }
-      )
+      @launcher = Puma::Launcher.new(puma_config, log_writer: log_writer)
+      @launcher.run
+    rescue Interrupt
+      Docyard.logger.info("\nShutting down preview server...")
     end
 
-    def shutdown_server(server)
-      puts "\nShutting down preview server..."
-      server.shutdown
+    def build_puma_config(app)
+      server_port = port
+
+      Puma::Configuration.new do |config|
+        config.bind "tcp://localhost:#{server_port}"
+        config.app app
+        config.workers 0
+        config.threads 1, 4
+        config.quiet
+      end
     end
   end
 end