Add server mode with live reload (rdoc --server)

[st0012]

A better attempt of #1151

Depends on: #1634

Implement rdoc --server[=PORT] for previewing documentation with automatic browser refresh on source file changes. The server parses all sources on startup, serves pages from memory via the Aliki generator, and watches for file modifications, additions, and deletions — re-parsing only what changed.

rdoc-server-demo.mp4

Changes

• New RDoc::Server (lib/rdoc/server.rb) — minimal HTTP server using Ruby's built-in TCPServer (no WEBrick or external dependencies)
  • Thread-per-connection with Connection: close
  • Persistent Aliki generator instance rendering pages to strings
  • In-memory page cache with full invalidation on changes
  • Live reload via inline JS polling /__status endpoint every 1 second
  • Background file watcher polling source file mtimes every 1 second
  • Incremental re-parse: only changed files are re-parsed, old data removed first
  • Detection of new and deleted source files
• --server[=PORT] CLI option (default port 4000) and rdoc:server Rake task
• RDoc::Store#remove_file — removes a file's entries from the store hashes
• RDoc::Store#clear_file_contributions — surgically removes a file's methods, constants, comments, includes, extends, and aliases from its classes/modules, preserving classes that span multiple files. Supports keep_position: for server re-parse to preserve comment ordering.
• RDoc::RDoc#relative_path_for — extracted path normalization (against options.root and options.page_dir) shared by parse_file and the server
• Darkfish#refresh_store_data — extracted for reuse by the server after re-parsing
• RDoc::Servlet → RDoc::RI::Servlet — moved to clarify RI-specific usage

Security & robustness

• Binds to 127.0.0.1 only (localhost)
• Path traversal protection in asset serving (File.expand_path containment check)
• Proper HTTP error responses: 400, 404, 405, 500
• 5-second IO.select read timeout on client sockets
• Mutex protects all store mutations, generator refresh, and cache invalidation atomically
• Individual parse_file errors rescued so one failure doesn't block remaining files
• Watcher thread uses @running flag with clean shutdown via Thread#join

Known limitations

• Full cache invalidation: any file change clears all cached pages. Rendering is fast (~ms per page); parsing is the expensive part and is done incrementally.
• Template/CSS changes: require server restart (only source files are watched).

[matzbot]

🚀 Preview deployment available at: https://c473c39c.rdoc-6cd.pages.dev (commit: 9511fd0)

[kou]

+1

[kou]

I don't have a strong opinion whether we re-implement our HTTP server or we use WEBrick but do we want to keep depending on WEBrick?

[st0012]

I think we can let it go and potentially merge the server implementation between RDoc and RI. But it'll be outside of the scope of the PR.

[tompng]

Same location comment will be removed with this change.

Example input:

# comment1
class A; end
# comment2
class A; end

Output:

<section class="description">
<p>comment1</p> <!-- this line disappears -->
<p>comment2</p>
</section>

I don't think these kind of reopening with comment is normally used, but the original deduplicating logic is clearly only for C code.

if location.parser == RDoc::Parser::C
  @comment_location.delete_if { |(_, l)| l == location }
end

Since reopening class with a comment is both included in the document in some case(different file), I think it's natural to accept the same thing written in a single file too.

[tompng]

A very edge case, comment_location[top_level] will be kept empty if reparsed file doesn't contain that ClassModule anymore, or a comment to the ClassModule is erased.
After this has happened, even every contribution files are removed, if cm.in_files.empty? won't be true.

I think one possible solution for this is:

def reparse_and_refresh(...)
  unless removed_files.empty?
    ...
    # Don't need to perform `@modules_hash.delete(cm.full_name)` logic
  end

  unless changed_files.empty?
    ...
  end

  if removed_files.any? || changed_files.any?
    # Check all classes/modules for empty comment_location entries
    # and perform `@modules_hash.delete(cm.full_name)` logic
  end
  ...
end