simple_english 0.6.0-x86_64-linux

data/lib/simple_english/client/daemon.rb

@@ -0,0 +1,233 @@
+# frozen_string_literal: true
+
+# HTTP client for the se daemon: probe, handshake, boot, lint. The
+# LanguageTool wire protocol lives in lib/simple_english/client/language_tool.rb.
+
+require "json"
+require "net/http"
+require "rbconfig"
+require "fileutils"
+require "uri"
+
+require_relative "../setup/fingerprint"
+require_relative "../version"
+
+module SimpleEnglish
+  module Client
+    module_function
+
+    DEFAULT_PORT = 8181
+    REQUEST_TIMEOUT = 30
+
+    # The executable that daemon advice tells you to run. Resolved
+    # from this file, so it names the code that is actually loaded:
+    # a checkout names its bin/se, a gem install names its bundled
+    # bin/se. $PROGRAM_NAME is wrong for library callers: their host
+    # script is not se.
+    def runner
+      File.expand_path("../../../bin/se", __dir__)
+    end
+
+    def url
+      ENV.fetch("SE_SERVER_URL") { "http://localhost:#{DEFAULT_PORT}" }
+    end
+
+    def post(uri, params, read_timeout: REQUEST_TIMEOUT)
+      Net::HTTP.start(uri.host, uri.port, open_timeout: 5,
+        read_timeout: read_timeout) do |http|
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request.set_form_data(params)
+        http.request(request)
+      end
+    end
+
+    private_class_method :post
+
+    # Full lint via the se daemon. Raw Markdown in, or code
+    # source with a language for the comment pipeline. nil when
+    # unreachable or the response is unusable, so callers can fall
+    # back without seeing a stack trace.
+    def lint(text, base_url: url, language: nil)
+      params = {"text" => text}
+      params["language"] = language if language
+      response = post(URI("#{base_url}/lint"), params)
+      return nil unless response.is_a?(Net::HTTPSuccess)
+      body = JSON.parse(response.body)
+      return nil unless body.is_a?(Array)
+      body.map do |hash|
+        Finding.new(line: hash.fetch("line"), column: hash["column"],
+          end_line: hash["end_line"], end_column: hash["end_column"],
+          rule: hash.fetch("rule"), message: hash.fetch("message"))
+      end
+    rescue SystemCallError, SocketError, Timeout::Error,
+      JSON::ParserError, TypeError
+      nil
+    end
+
+    # The daemon handshake: GET / answers {version, pid, gem_digest,
+    # rules_digest}. Returns the handshake Hash for an se daemon,
+    # :foreign for a reachable responder that is not one (an older
+    # release, a foreign service) - those still lint, the caller
+    # cannot check them - or nil when nothing answers. Unreachable
+    # means boot. Foreign means lint but say so.
+    def info(base_url: url)
+      uri = URI(base_url)
+      response = Net::HTTP.start(uri.host, uri.port, open_timeout: 1,
+        read_timeout: 2) { |http| http.get("/") }
+      return :foreign unless response.is_a?(Net::HTTPSuccess)
+      data = JSON.parse(response.body)
+      # The whole contract or nothing: a responder with a string pid
+      # or a missing field is not a daemon we can reason about.
+      return :foreign unless data.is_a?(Hash) &&
+        data["version"].is_a?(String) && data["pid"].is_a?(Integer) &&
+        data["pid"].positive? && data["gem_digest"].is_a?(String) &&
+        data["rules_digest"].is_a?(String)
+      data
+    rescue Errno::ECONNRESET, Errno::EPIPE, EOFError, Net::ReadTimeout,
+      JSON::ParserError, TypeError
+      # Something holds the port but answers nothing usable. A read
+      # timeout is that too: the request went out, nothing came back.
+      :foreign
+    rescue Errno::ECONNREFUSED, SocketError, Timeout::Error
+      nil
+    end
+
+    # True when the daemon answers. Starts it when the port is
+    # cold and we own the default URL. A running daemon is never
+    # replaced by a lint: `se serve` owns that. A custom
+    # SE_SERVER_URL belongs to someone else, so never spawn against
+    # it. It returns false when unusable. The caller owns the exit
+    # status. Diagnostics go to stderr here, where the cause is
+    # known.
+    def ensure_up(install: SimpleEnglish::Install.from_env)
+      daemon = info
+      return boot(install) if daemon.nil?
+      check_daemon(daemon)
+    end
+
+    # An answered probe, classified and said out loud: a foreign
+    # responder or a different build. Returns true: there is a daemon
+    # to lint against, so the lint proceeds. Every path that holds a
+    # handshake result goes through here, so no caller can lint
+    # silently.
+    def check_daemon(daemon)
+      # Reachable but not handshake-capable (an older release, a
+      # foreign service): lint against it, there is nothing to check
+      # or replace automatically. Say so: a silent stale lint is the
+      # bug the handshake exists to catch.
+      if daemon == :foreign
+        if ENV["SE_SERVER_URL"]
+          warn "se: daemon at #{url} is not a handshake-capable se daemon. " \
+            "Update it (pull a newer image or rebuild). " \
+            "It is not restarted automatically."
+        else
+          warn "se: daemon at #{url} is not a handshake-capable se daemon. " \
+            "Run `#{runner} serve` to replace it."
+        end
+        return true
+      end
+      return true if daemon["gem_digest"] == Fingerprint.gem
+      warn_mismatched_code(daemon)
+      true
+    end
+
+    # The daemon is unreachable. Start it when we own the default
+    # URL, fail fast otherwise.
+    def boot(install)
+      if ENV["SE_SERVER_URL"]
+        warn "error: SE_SERVER_URL is set but #{url} does not answer."
+        return false
+      end
+      # Preflight everything the spawn needs: a missing prerequisite
+      # must fail fast with the real blocker named, not spawn a
+      # doomed child and wait out 90 s.
+      unless install.executable?
+        warn install.setup_error
+        return false
+      end
+      # One boot at a time: a concurrent lint that also found the
+      # port cold waits here, re-checks, and skips its own spawn.
+      # Whatever answers on wake is classified like the first probe:
+      # the loser must get the same warnings, never a silent lint
+      # against the winner's rules or build.
+      with_spawn_lock do
+        daemon = info
+        unless daemon
+          warn "se: daemon not running; starting it (first lint may take a few seconds)..."
+          spawn_daemon
+          daemon = wait_for { info }
+        end
+        if daemon
+          check_daemon(daemon)
+        else
+          warn "error: se daemon did not come up. Run `#{runner} serve` and read its output."
+          false
+        end
+      end
+    end
+
+    # The daemon runs different code: older, or another build of
+    # this version (a dev checkout beside the installed gem). A
+    # lint never stops a daemon: `se serve` owns replacement. Say
+    # what runs and how to fix it, then lint against it: a stale
+    # lint with a warning beats a refused lint.
+    def warn_mismatched_code(daemon)
+      if newer_daemon?(daemon)
+        # `se serve` from this install boots an older daemon in its
+        # place. The fix is updating this gem, not the daemon.
+        warn "se: daemon at #{url} runs se #{daemon["version"]}, newer than this install " \
+          "(#{VERSION}). Update this gem. Linting against it meanwhile."
+        return
+      end
+      fix = ENV["SE_SERVER_URL"] ? "It is not restarted automatically." :
+        "Run `#{runner} serve --detached` to restart it."
+      warn "se: daemon at #{url} runs se #{daemon["version"]}, different code than this install " \
+        "(#{VERSION}). #{fix} Linting against it meanwhile."
+    end
+
+    # A per-user lock keyed by the port: daemon ownership is scoped
+    # to the port, so concurrent lints coordinate across installs.
+    # flock releases when the block ends, even on
+    # failure.
+    def with_spawn_lock
+      dir = File.join(Dir.home, ".cache", "simple_english")
+      FileUtils.mkdir_p(dir)
+      port = URI(url).port
+      File.open(File.join(dir, "spawn-#{port}.lock"), "w") do |lock|
+        lock.flock(File::LOCK_EX)
+        yield
+      end
+    end
+
+    # Boots `se serve` as a detached child, output discarded: the
+    # daemon must outlive the caller. Extra arguments (a port, a
+    # dev-log path) are forwarded to the child serve.
+    def spawn_daemon(*serve_args)
+      bin = File.expand_path("../../../bin/se", __dir__)
+      Process.spawn(RbConfig.ruby, bin, "serve", *serve_args,
+        out: File::NULL, err: File::NULL)
+    end
+
+    def wait_for(seconds: 90)
+      deadline = Time.now + seconds
+      until Time.now > deadline
+        result = yield
+        return result if result
+        sleep 0.5
+      end
+      false
+    end
+
+    # The handshake reports the daemon's version: a digest mismatch
+    # alone cannot tell older from newer. A malformed version counts
+    # as not newer, so the warning path decides what to do with it.
+    def newer_daemon?(daemon)
+      Gem::Version.new(daemon["version"]) > Gem::Version.new(VERSION)
+    rescue ArgumentError
+      false
+    end
+
+    private_class_method :boot, :check_daemon, :warn_mismatched_code,
+      :newer_daemon?, :with_spawn_lock
+  end
+end

data/lib/simple_english/client/language_tool.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+# The LanguageTool wire protocol: form posts to /v2/check, and
+# matches mapped back to findings. Runs daemon-side (Engine calls it
+# against the inner native server) and in tests. The se daemon client - probe,
+# trust, boot - lives in client/daemon.rb.
+#
+# The LanguageTool namespace is shared with setup/languagetool.rb,
+# which holds the pinned-distro facts. This file adds the client
+# that speaks to that distro.
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "../lint/plain_text"
+
+module SimpleEnglish
+  module LanguageTool
+    module Client
+      module_function
+
+      REQUEST_TIMEOUT = 30
+
+      def post(uri, params, read_timeout: REQUEST_TIMEOUT)
+        Net::HTTP.start(uri.host, uri.port, open_timeout: 5,
+          read_timeout: read_timeout) do |http|
+          request = Net::HTTP::Post.new(uri.request_uri)
+          request.set_form_data(params)
+          http.request(request)
+        end
+      end
+
+      private_class_method :post
+
+      # Pattern rules. `payload` is Markdown-stripped text (String) or an
+      # AnnotatedText::Result (code comments): one payload interface,
+      # #lt_params and #locate, either side of the daemon's LT request.
+      # The caller owns the enabled rule IDs (the daemon captures them
+      # at boot). There is no default, so no call silently lints with
+      # every rule disabled.
+      def check(payload, enabled_rules:, base_url:)
+        payload = to_payload(payload)
+        params = {"language" => "en",
+                  "enabledRules" => Array(enabled_rules).join(","),
+                  "enabledOnly" => "true"}.merge(payload.lt_params)
+        response = post(URI("#{base_url}/v2/check"), params)
+        parse_matches(JSON.parse(response.body).fetch("matches"), payload)
+      end
+
+      def parse_matches(matches, payload)
+        payload = to_payload(payload)
+        matches.map do |match|
+          offset = match.fetch("offset")
+          line, column = payload.locate(offset)
+          end_line, end_column = payload.locate(offset + match.fetch("length"))
+          Finding.new(line: line, column: column,
+            end_line: end_line, end_column: end_column,
+            rule: match.fetch("rule").fetch("id"),
+            message: with_context(match.fetch("message"), match))
+        end
+      end
+
+      # Prefix the offending text, so a finding says what to change,
+      # not only how. Context positions use Java UTF-16 code units.
+      def with_context(message, match)
+        context = match["context"] or return message
+        matched = utf16_slice(context.fetch("text", ""),
+          context.fetch("offset", 0).to_i, context.fetch("length", 0).to_i)
+        matched.empty? ? message : "\"#{matched}\" - #{message}"
+      end
+
+      def utf16_slice(text, offset, length)
+        first = utf16_index(text, offset)
+        last = utf16_index(text, offset + length)
+        text[first...last]
+      end
+
+      def utf16_index(text, offset)
+        units = 0
+        text.each_char.with_index do |char, index|
+          return index if units >= offset
+          units += (char.ord > 0xFFFF) ? 2 : 1
+        end
+        text.length
+      end
+
+      def to_payload(payload)
+        payload.is_a?(String) ? PlainText.new(payload) : payload
+      end
+
+      private_class_method :to_payload, :with_context, :utf16_slice, :utf16_index
+    end
+  end
+end

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/daemon/http.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+# Minimal HTTP/1.1 wire framing for the daemon's outer server. Serving
+# one request per connection (Connection: close) keeps this simple: no
+# chunked bodies, no pipelining.
+
+require "json"
+
+module SimpleEnglish
+  module HTTP
+    module_function
+
+    # Reads one HTTP request from io: request line, headers, then
+    # Content-Length bytes of body. nil when malformed or the peer
+    # hung up.
+    def read_request(io)
+      request_line = io.gets
+      parts = request_line ? request_line.split(" ") : []
+      return nil if parts.length < 2
+      content_length = 0
+      while (line = io.gets)
+        break if line == "\r\n" || line == "\n"
+        name, value = line.split(":", 2)
+        next unless value
+        content_length = value.strip.to_i if name.casecmp?("content-length")
+      end
+      return nil if content_length.negative?
+      body = content_length.zero? ? +"" : io.read(content_length)
+      {method: parts[0], path: parts[1], body: body}
+    end
+
+    # Writes a minimal HTTP/1.1 response and closes the logical
+    # connection (Connection: close): status line, always-JSON headers,
+    # Content-Length, then the body.
+    def write_response(io, status:, body:, content_type: "application/json")
+      reason = {200 => "OK", 404 => "Not Found",
+                500 => "Internal Server Error"}.fetch(status, "Unknown")
+      io.write("HTTP/1.1 #{status} #{reason}\r\n" \
+        "Content-Type: #{content_type}\r\n" \
+        "Content-Length: #{body.bytesize}\r\n" \
+        "Connection: close\r\n\r\n")
+      io.write(body)
+    end
+
+    # One thread per request: lint can take seconds, so a slow request
+    # 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"
+        # 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
+          # handler decodes it. A raw body lints "text=Don%27t...".
+          # The optional language switches to the code-comment pipeline.
+          params = URI.decode_www_form(request[:body]).to_h
+          write_response(client, status: 200,
+            body: SimpleEnglish::Engine.lint_json(params["text"],
+              base_url: "http://localhost:#{port + 1}",
+              language: params["language"], enabled_rules: enabled_rules))
+        rescue => e
+          write_response(client, status: 500,
+            body: JSON.generate({"error" => e.message}))
+        end
+      else
+        write_response(client, status: 404,
+          body: JSON.generate({"error" => "not found"}))
+      end
+    ensure
+      client.close
+    end
+  end
+end