simple_english 0.2.0 → 0.4.0

data/lib/simple_english/daemon/engine.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# The complete lint engine, daemon-side. Never call SimpleEnglish.lint_text
+# here: that call probes the daemon and recurses into the server.
+# The engine reads nothing from disk: the caller captures the enabled
+# rule IDs once at daemon boot (Server.start) and passes them in.
+# LintPlan owns what kind of lint an input is. This module executes
+# the plan.
+
+require "json"
+
+module SimpleEnglish
+  module Engine
+    module_function
+
+    def lint(text, base_url:, language: nil,
+      enabled_rules: SimpleEnglish::LanguageTool.rule_ids)
+      plan = SimpleEnglish::LintPlan.call(text, language)
+      return [] if plan.nil?
+      if plan == :prose
+        stripped = SimpleEnglish::Markdown.strip(text)
+        (SimpleEnglish::Counts.check(stripped) +
+          SimpleEnglish::LanguageTool::Client.check(stripped, base_url: base_url,
+            enabled_rules: enabled_rules))
+          .sort_by { |finding| [finding.line, finding.rule] }
+      else
+        SimpleEnglish::LanguageTool::Client.check(
+          SimpleEnglish::AnnotatedText.build(text, plan), base_url: base_url,
+          enabled_rules: enabled_rules
+        )
+      end
+    end
+
+    def lint_json(text, base_url:, language: nil,
+      enabled_rules: SimpleEnglish::LanguageTool.rule_ids)
+      JSON.generate(lint(text, base_url: base_url, language: language,
+        enabled_rules: enabled_rules).map(&:to_h))
+    end
+  end
+end

data/lib/simple_english/{http.rb → daemon/http.rb}

@@ -43,14 +43,20 @@ module SimpleEnglish
     end
 
     # One thread per request: lint can take seconds, so a slow request
-    # must not block readiness probes or other clients.
-    def handle_client(client, port:)
+    # must not block readiness probes or other clients. The enabled
+    # rule IDs and the handshake info are frozen at boot (Server.start)
+    # and passed through.
+    def handle_client(client, port:, enabled_rules:, info: {})
       request = read_request(client)
       if request.nil?
         # Malformed request or immediate hangup: nothing to answer.
       elsif request[:method] == "HEAD"
-        # Client.up? does http.head("/") and treats any response as up.
+        # Older CLIs probe with HEAD and treat any response as up.
         write_response(client, status: 200, body: "")
+      elsif request[:method] == "GET" && request[:path] == "/"
+        # The handshake: the daemon reports its version, pid, and the
+        # gem/rules digests the client compares against its own.
+        write_response(client, status: 200, body: JSON.generate(info))
       elsif request[:method] == "POST" && request[:path] == "/lint"
         begin
           # Ruling 2026-09-24: Client.lint posts form-encoded data, so the
@@ -60,7 +66,7 @@ module SimpleEnglish
           write_response(client, status: 200,
             body: SimpleEnglish::Engine.lint_json(params["text"],
               base_url: "http://localhost:#{port + 1}",
-              language: params["language"]))
+              language: params["language"], enabled_rules: enabled_rules))
         rescue => e
           write_response(client, status: 500,
             body: JSON.generate({"error" => e.message}))

data/lib/simple_english/{server.rb → daemon/server.rb}

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 # The se daemon: process lifecycle only. The wire protocol lives in
-# lib/simple_english/http.rb, the lint engine in lib/simple_english/engine.rb.
+# lib/simple_english/daemon/http.rb, the lint engine in
+# lib/simple_english/daemon/engine.rb.
 # Failures raise typed errors (PortInUse, SetupError, InnerDied,
 # InnerTimeout). bin/se owns turning them into warnings and exit codes.
 
@@ -11,7 +12,10 @@ require "socket"
 require "tempfile"
 require "tmpdir"
 
-require_relative "install"
+require_relative "../setup/install"
+require_relative "../client/daemon"
+require_relative "../setup/fingerprint"
+require_relative "../version"
 
 module SimpleEnglish
   module Server
@@ -40,24 +44,123 @@ module SimpleEnglish
     # Probes both loopback families: on IPv6-first resolvers a "localhost"
     # probe falls back to IPv4 and misses an IPv6 listener.
     def assert_port_free(port)
+      raise PortInUse, port unless port_free?(port)
+    end
+
+    def port_free?(port)
       ["127.0.0.1", "::1"].each do |address|
         TCPServer.new(address, port).close
-      rescue Errno::EADDRNOTAVAIL
+      rescue Errno::EADDRNOTAVAIL, Errno::EAFNOSUPPORT
+        # One family may be missing on this host (EADDRNOTAVAIL, or
+        # EAFNOSUPPORT when the kernel has no IPv6 at all): skip it
+        # and probe the other. A rescue at method scope returns here
+        # and never probes the second family.
         next
       end
+      true
     rescue Errno::EADDRINUSE
-      raise PortInUse, port
+      false
     rescue Errno::EACCES
       raise ServerError, "port #{port} cannot be bound. Use a port above 1024."
     end
 
+    # `se serve` over a live daemon (gem upgrade): when
+    # one of our daemons holds the port (it answers the
+    # handshake), stop it and take over the port. A service that
+    # does not answer the handshake, pre-handshake daemon included,
+    # keeps the PortInUse error: those need a manual look.
+    def takeover(port)
+      daemon = Client.info(base_url: "http://localhost:#{port}")
+      return unless daemon.is_a?(Hash)
+      stop(daemon["pid"])
+      # The outer listener closes first. The inner JVM takes seconds
+      # longer. Both ports must free, or the next boot hits the inner
+      # port and dies.
+      deadline = Time.now + 10
+      sleep 0.2 until Time.now > deadline ||
+          !Client.info(base_url: "http://localhost:#{port}").is_a?(Hash) &&
+              port_free?(port + 1)
+    end
+
+    # Graceful only. SIGKILL skips the TERM trap and the inner JVM
+    # teardown. The orphan still holds port + 1 and breaks the next
+    # boot. The pid comes off the wire, so only a positive integer is
+    # TERMed: 0 signals the caller's own process group, a negative
+    # one every process the user may signal.
+    def stop(pid)
+      return nil unless pid.is_a?(Integer) && pid > 1
+      Process.kill("TERM", pid)
+    rescue Errno::ESRCH, Errno::EPERM
+      nil
+    end
+
+    # Everything a boot needs on the machine, checked before the
+    # takeover stops the old daemon: a reload that cannot boot must
+    # leave the running daemon alive.
+    def preflight_install(install)
+      return if File.exist?(install.server_jar) && install.java?
+      raise Install::SetupError,
+        install.java? ? install.setup_error : install.java_message
+    end
+    private_class_method :preflight_install
+
+    # `se serve --detached`: replace any se daemon on the port, then
+    # boot a plain foreground serve as a detached child - the same
+    # shape the auto-boot spawns. The parent returns once the
+    # handshake answers. nil means the child never came up, and the
+    # visible serve (same command, no flag) shows why. dev_log is
+    # forwarded so a detached daemon can still get a log file.
+    def start_detached(port: Client::DEFAULT_PORT, install: Install.from_env,
+      dev_log: nil)
+      preflight_install(install)
+      takeover(port)
+      # A foreign port holder survives the takeover untouched: fail
+      # in milliseconds like the foreground boot, not after the
+      # 90 s spawn timeout.
+      assert_port_free(port)
+      assert_port_free(port + 1)
+      args = ["--port", port.to_s]
+      args.concat(["--dev-log", dev_log]) if dev_log
+      pid = Client.spawn_daemon(*args)
+      # The child gives its inner JVM TIMEOUT_SECONDS to boot, and
+      # the handshake answers only after that: wait the child's own
+      # budget, not the default 90 s, or a slow boot reads as
+      # failure while the child is still coming up.
+      daemon = Client.wait_for(
+        seconds: SimpleEnglish::LanguageTool::TIMEOUT_SECONDS + 10
+      ) { Client.info(base_url: "http://localhost:#{port}") }
+      return daemon if daemon.is_a?(Hash)
+      # Readiness failed. The child is either dead (InnerTimeout and
+      # InnerDied make it exit itself) or a straggler that later
+      # takes over the port from whatever daemon comes next.
+      # Stop it either way, and reap so nothing is left behind.
+      stop(pid)
+      begin
+        Process.wait(pid)
+      rescue SystemCallError
+        # The child already exited on its own (InnerTimeout,
+        # InnerDied): only the reap is left.
+      end
+      nil
+    end
+
     def start(port: Client::DEFAULT_PORT, install: Install.from_env, log: $stderr)
+      rules_dir = Dir.mktmpdir("se-rules")
+      # The enabled IDs come from the staged file, so what LT loads
+      # and what each request enables can never diverge.
+      staged = stage_rules(rules_dir)
+      enabled_rules = SimpleEnglish::LanguageTool.rule_ids
+      daemon_info = {"version" => VERSION, "pid" => Process.pid,
+                     "gem_digest" => Fingerprint.gem,
+                     "rules_digest" => Fingerprint.sha(File.read(staged))}
+      # Preflight everything the replacement needs before the
+      # takeover stops the old daemon.
+      preflight_install(install)
+      takeover(port)
       assert_port_free(port)
       # The inner JVM lives on port + 1. Guard it too so an occupied
       # inner port raises in milliseconds instead of timing out later.
       assert_port_free(port + 1)
-      rules_dir = Dir.mktmpdir("se-rules")
-      stage_rules(rules_dir)
       # The inner JVM's stderr goes to a file so failure messages can quote
       # its first line. Only an explicitly opened dev log (a File) is reused
       # for that. $stderr reports path "<STDERR>", so it creates a file
@@ -103,7 +206,10 @@ module SimpleEnglish
         # Select timeout on an idle socket: loop back and select again.
         next if ready.nil?
         client = server.accept
-        Thread.new(client) { |c| HTTP.handle_client(c, port: port) }
+        Thread.new(client) { |c|
+          HTTP.handle_client(c, port: port,
+            enabled_rules: enabled_rules, info: daemon_info)
+        }
       rescue IOError, Errno::EBADF
         # A trap or the inner-death monitor closed the listener. This
         # happens during the select, or between select and accept.

data/lib/simple_english/{extractor.rb → lint/extractor.rb}

@@ -20,7 +20,12 @@ module SimpleEnglish
       ".java" => "java",
       ".sh" => "bash",
       ".kt" => "kotlin",
-      ".cs" => "csharp"
+      ".cs" => "csharp",
+      ".cpp" => "cpp",
+      ".cc" => "cpp",
+      ".cxx" => "cpp",
+      ".hpp" => "cpp",
+      ".h" => "cpp"
     }.freeze
 
     module_function

data/lib/simple_english/lint/finding.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# One lint result. Positions are 1-based. The end position is exclusive.
+# Counting findings have no columns or end positions. Findings from an older
+# daemon can have a start column without an end position.
+
+module SimpleEnglish
+  Finding = Struct.new(:line, :column, :end_line, :end_column, :rule, :message)
+end

data/lib/simple_english/lint/lint_plan.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# One decision, two callers: the CLI (SimpleEnglish.lint_file) and
+# the daemon (Engine.lint) must agree on what kind of lint an input
+# is. The CLI decides to skip comment-free files without a boot.
+# The daemon decides again on its side of the wire. Both call this
+# module, so the two tiers cannot drift.
+
+module SimpleEnglish
+  module LintPlan
+    module_function
+
+    # Returns :prose when there is no language (the Markdown
+    # pipeline), nil for a comment-free code file (nothing to lint:
+    # no boot, no POST), or the comment spans for a code file.
+    def call(text, language)
+      return :prose unless language
+      spans = SimpleEnglish::Extractor.comment_spans(text, language)
+      spans.empty? ? nil : spans
+    end
+  end
+end

data/lib/simple_english/{markdown.rb → lint/markdown.rb}

@@ -21,21 +21,39 @@ module SimpleEnglish
     module_function
 
     # Blank out code and other non-prose blocks and neutralize inline
-    # code and heading markers. The line count stays identical to the
-    # source.
+    # code and heading markers. Line count and UTF-16 widths stay identical
+    # to the source so LanguageTool offsets remain source positions.
     def strip(text)
-      lines = text.lines.map(&:chomp)
-      blank_rows(text).each { |row| lines[row] = "" }
-      lines.map { |line| strip_line(line) }.join("\n")
+      blank = blank_rows(text).to_h { |row| [row, true] }
+      text.lines.each_with_index.map do |line, row|
+        ending = if line.end_with?("\r\n")
+          "\r\n"
+        elsif line.end_with?("\n")
+          "\n"
+        else
+          ""
+        end
+        body = line.delete_suffix(ending)
+        (blank[row] ? spaces_for(body) : strip_line(body)) + ending
+      end.join
     end
 
     def strip_line(line)
-      # Width-preserving replacements, so a finding column points at
-      # the source line, not at the stripped copy.
-      line.gsub(/`[^`]*`/) { |code| "X" * code.length }
+      # Width-preserving replacements keep LanguageTool positions aligned
+      # with the source.
+      line
+        .gsub(/`[^`]*`/) { |code| "X" * utf16_length(code) }
         .sub(/\A\#{1,6} /) { |marker| " " * marker.length }
     end
 
+    def spaces_for(text)
+      " " * utf16_length(text)
+    end
+
+    def utf16_length(text)
+      text.each_char.sum { |char| (char.ord > 0xFFFF) ? 2 : 1 }
+    end
+
     # A vertical list is not one paragraph: each list item is its own.
     # Paragraph boundaries come from the tree-sitter Markdown grammar,
     # so lazy continuations and interrupted lists match the spec
@@ -97,7 +115,7 @@ module SimpleEnglish
       TreeSitterLanguagePack.get_parser("markdown").parse(text).root_node
     end
 
-    private_class_method :strip_line, :node_rows, :blank_rows, :each_node,
-      :inside_list_item?, :parse
+    private_class_method :strip_line, :spaces_for, :utf16_length, :node_rows,
+      :blank_rows, :each_node, :inside_list_item?, :parse
   end
 end

data/lib/simple_english/lint/plain_text.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  # The plain-text payload for /v2/check, duck-compatible with
+  # AnnotatedText::Result: #lt_params and #locate.
+  PlainText = Struct.new(:text) do
+    def lt_params
+      {"text" => text}
+    end
+
+    # LanguageTool reports offsets in Java UTF-16 code units.
+    # Return a 1-based line and UTF-16 column for a 0-based offset.
+    def locate(utf16_offset)
+      line = 1
+      column = 1
+      units = 0
+      text.each_char do |char|
+        return [line, column] if units >= utf16_offset
+        units += (char.ord > 0xFFFF) ? 2 : 1
+        if char == "\n"
+          line += 1
+          column = 1
+        else
+          column += (char.ord > 0xFFFF) ? 2 : 1
+        end
+      end
+      [line, column]
+    end
+  end
+end

data/lib/simple_english/{result.rb → lint/result.rb}

@@ -3,7 +3,7 @@
 module SimpleEnglish
   module AnnotatedText
     # The payload for code comments. Duck interface shared with
-    # Client::PlainText: #lt_params (the form data for LanguageTool)
+    # PlainText: #lt_params (the form data for LanguageTool)
     # and #locate (a match offset back to file line and column).
     Result = Struct.new(:source, :segments, :stream) do
       def lt_params

data/lib/simple_english/{config.rb → setup/config.rb}

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
-# .simple-english.yml: ignore (path globs, matched against the paths given
-# on the command line) and disabled-rules. Loaded from the CWD.
+# .simple-english.yml: ignore (path globs, matched against the paths
+# given on the command line) and disabled-rules (rule IDs dropped
+# from every file). Loaded from the CWD.
 
 module SimpleEnglish
   module Config

data/lib/simple_english/setup/fingerprint.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Fingerprints for the daemon handshake. `gem` identifies the code and
+# built-in rules a daemon runs: any release that changes lint behavior
+# changes it, and nothing else does. `sha` covers the staged rule
+# content wherever the caller resolved it.
+
+require_relative "languagetool"
+
+module SimpleEnglish
+  module Fingerprint
+    module_function
+
+    # Hash everything the daemon can execute, not a curated list: a
+    # curated list goes stale the first time a new file is forgotten,
+    # and a missed file means silent staleness, the exact bug the
+    # handshake exists to catch. The accepted cost: a release that
+    # only changes caller-side code triggers one needless restart.
+    # ponytail: whole-lib glob. If restarts ever hurt, curate per-file.
+    def gem
+      files = Dir.glob(File.expand_path("../../**/*.rb", __dir__)).sort
+      files << LanguageTool::RULES_FILE
+      # Each file is length-prefixed: bare concatenation cannot tell
+      # ["ab", "c"] from ["a", "bc"], so bytes moved across a file
+      # boundary leave the digest unchanged.
+      framed = files.map do |path|
+        content = File.read(path)
+        "#{content.bytesize}\n#{content}"
+      end
+      sha(framed.join)
+    end
+
+    def sha(content)
+      require "digest"
+      ::Digest::SHA256.hexdigest(content)
+    end
+  end
+end

data/lib/simple_english/{install.rb → setup/install.rb}

@@ -13,11 +13,12 @@ module SimpleEnglish
     class SetupError < StandardError
     end
 
-    attr_reader :cache_dir, :java
+    attr_reader :cache_dir, :java, :java_source
 
-    def initialize(cache_dir:, java: nil)
+    def initialize(cache_dir:, java: nil, java_source: nil)
       @cache_dir = cache_dir
       @java = java
+      @java_source = java_source
     end
 
     # The one place the environment is read. SE_JAVA wins outright,
@@ -25,15 +26,21 @@ module SimpleEnglish
     # Otherwise the code probes the PATH candidate by running it,
     # because a file can exist and still be the macOS stub that
     # reports no runtime. The last resort is the Homebrew location,
-    # which sits outside PATH.
+    # which sits outside PATH. java_source records which of the three
+    # won, so `se setup` can say so.
     def self.from_env(env = ENV)
       cache = File.expand_path(env.fetch(LanguageTool::CACHE_DIR_ENV) do
         File.join(Dir.home, ".cache", "se")
       end)
-      java = env[LanguageTool::JAVA_ENV] ||
-        ("java" if probe?("java", env)) ||
-        (LanguageTool::HOMEBREW_JAVA if File.executable?(LanguageTool::HOMEBREW_JAVA))
-      new(cache_dir: cache, java: java)
+      java, source =
+        if (explicit = env[LanguageTool::JAVA_ENV])
+          [explicit, :env]
+        elsif probe?("java", env)
+          ["java", :path]
+        elsif File.executable?(LanguageTool::HOMEBREW_JAVA)
+          [LanguageTool::HOMEBREW_JAVA, :homebrew]
+        end
+      new(cache_dir: cache, java: java, java_source: source)
     end
 
     # Runs the candidate under the given PATH, isolated from this
@@ -50,8 +57,11 @@ module SimpleEnglish
 
     def java!
       return java if java?
-      raise SetupError,
-        "java not found. Install a JRE (on macOS: brew install openjdk), " \
+      raise SetupError, java_message
+    end
+
+    def java_message
+      "java not found. Install a JRE (on macOS: brew install openjdk), " \
         "or set SE_JAVA to your java binary."
     end