simple_english 0.3.0 → 0.4.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_english
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - TonyCTHsu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tree_sitter_language_pack
@@ -39,63 +39,63 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: rubyzip
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
-  type: :runtime
+        version: '13.0'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '13.0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '13.0'
+        version: '6.0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: minitest-mock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.27'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '6.0'
+        version: '5.27'
 - !ruby/object:Gem::Dependency
-  name: minitest-mock
+  name: rubyzip
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.27'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.27'
+        version: '3.0'
 - !ruby/object:Gem::Dependency
-  name: json
+  name: rexml
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rexml
+  name: json
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -135,25 +135,28 @@ files:
 - bin/se
 - docs/RULES.md
 - lib/simple_english.rb
-- lib/simple_english/annotated_text.rb
 - lib/simple_english/cli.rb
-- lib/simple_english/client.rb
-- lib/simple_english/config.rb
-- lib/simple_english/counts.rb
-- lib/simple_english/engine.rb
-- lib/simple_english/extractor.rb
-- lib/simple_english/finding.rb
-- lib/simple_english/http.rb
-- lib/simple_english/install.rb
-- lib/simple_english/languagetool.rb
-- lib/simple_english/markdown.rb
-- lib/simple_english/paragraph.rb
-- lib/simple_english/plain_text.rb
-- lib/simple_english/result.rb
-- lib/simple_english/segment.rb
-- lib/simple_english/server.rb
-- lib/simple_english/span.rb
-- lib/simple_english/suppressions.rb
+- lib/simple_english/client/daemon.rb
+- lib/simple_english/client/language_tool.rb
+- lib/simple_english/daemon/engine.rb
+- lib/simple_english/daemon/http.rb
+- lib/simple_english/daemon/server.rb
+- lib/simple_english/lint/annotated_text.rb
+- lib/simple_english/lint/counts.rb
+- lib/simple_english/lint/extractor.rb
+- lib/simple_english/lint/finding.rb
+- lib/simple_english/lint/lint_plan.rb
+- lib/simple_english/lint/markdown.rb
+- lib/simple_english/lint/paragraph.rb
+- lib/simple_english/lint/plain_text.rb
+- lib/simple_english/lint/result.rb
+- lib/simple_english/lint/segment.rb
+- lib/simple_english/lint/span.rb
+- lib/simple_english/lint/suppressions.rb
+- lib/simple_english/setup/config.rb
+- lib/simple_english/setup/fingerprint.rb
+- lib/simple_english/setup/install.rb
+- lib/simple_english/setup/languagetool.rb
 - lib/simple_english/version.rb
 - rules/simple-english.xml
 homepage: https://github.com/TonyCTHsu/simple-english
@@ -162,7 +165,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/TonyCTHsu/simple-english
   source_code_uri: https://github.com/TonyCTHsu/simple-english
-  changelog_uri: https://github.com/TonyCTHsu/simple-english/blob/v0.3.0/CHANGELOG.md
+  changelog_uri: https://github.com/TonyCTHsu/simple-english/blob/v0.4.0/CHANGELOG.md
 post_install_message:
 rdoc_options: []
 require_paths:

data/lib/simple_english/client.rb

@@ -1,166 +0,0 @@
-# frozen_string_literal: true
-
-# HTTP client for the LanguageTool server and the se daemon.
-
-require "json"
-require "net/http"
-require "rbconfig"
-require "uri"
-
-require_relative "plain_text"
-require_relative "languagetool"
-
-module SimpleEnglish
-  module Client
-    module_function
-
-    # LanguageTool reports offsets and lengths in Java UTF-16 code units.
-    # Return a 1-based line and UTF-16 column for its 0-based offset.
-    def offset_to_position(text, offset)
-      line = 1
-      column = 1
-      units = 0
-      text.each_char do |char|
-        return [line, column] if units >= 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
-
-    DEFAULT_PORT = 8181
-    REQUEST_TIMEOUT = 30
-
-    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
-
-    # 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.
-    def check(payload, base_url: url)
-      payload = to_payload(payload)
-      params = {"language" => "en",
-                "enabledRules" => SimpleEnglish::LanguageTool.rule_ids.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
-
-    # 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
-
-    def up?(base_url: url)
-      uri = URI(base_url)
-      Net::HTTP.start(uri.host, uri.port, open_timeout: 1,
-        read_timeout: 2) { |http| http.head("/") }
-      true
-    rescue Errno::ECONNREFUSED, SocketError, Timeout::Error
-      false
-    end
-
-    # True when the daemon answers. Starts it when we own the default
-    # URL. 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)
-      return true if up?
-      if ENV["SE_SERVER_URL"]
-        warn "error: SE_SERVER_URL is set but #{url} does not answer."
-        return false
-      end
-      unless File.exist?(install.server_jar)
-        warn install.setup_error
-        return false
-      end
-      warn "se: daemon not running; starting it (first lint takes ~15s)..."
-      bin = File.expand_path("../../bin/se", __dir__)
-      Process.spawn(RbConfig.ruby, bin, "serve", out: File::NULL, err: File::NULL)
-      deadline = Time.now + 90
-      until Time.now > deadline
-        return true if up?
-        sleep 0.5
-      end
-      warn "error: se daemon did not come up. Run `se serve` and read its output."
-      false
-    end
-  end
-end

data/lib/simple_english/engine.rb

@@ -1,31 +0,0 @@
-# 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.
-
-require "json"
-
-module SimpleEnglish
-  module Engine
-    module_function
-
-    def lint(text, base_url:, language: nil)
-      if language
-        spans = SimpleEnglish::Extractor.comment_spans(text, language)
-        spans.empty? ? [] :
-          SimpleEnglish::Client.check(
-            SimpleEnglish::AnnotatedText.build(text, spans), base_url: base_url
-          )
-      else
-        stripped = SimpleEnglish::Markdown.strip(text)
-        (SimpleEnglish::Counts.check(stripped) +
-          SimpleEnglish::Client.check(stripped, base_url: base_url))
-          .sort_by { |finding| [finding.line, finding.rule] }
-      end
-    end
-
-    def lint_json(text, base_url:, language: nil)
-      JSON.generate(lint(text, base_url: base_url, language: language).map(&:to_h))
-    end
-  end
-end

data/lib/simple_english/languagetool.rb

@@ -1,143 +0,0 @@
-# frozen_string_literal: true
-
-# The pinned LanguageTool distro: its version, its rules file, and the
-# downloader. Everything that resolves "where it is on this machine and
-# which java runs it" lives in Install. The engine runs as the daemon's
-# inner HTTP server (lib/simple_english/server.rb).
-
-module SimpleEnglish
-  module LanguageTool
-    RULES_FILE = File.expand_path("../../rules/simple-english.xml", __dir__)
-    # The only place a LanguageTool version number appears. `se
-    # setup` downloads this version, and every jar path derives from it. No
-    # env var can point at another one.
-    LT_VERSION = "6.6"
-    CACHE_DIR_ENV = "SE_CACHE_DIR"
-    JAVA_ENV = "SE_JAVA"
-    # macOS ships a /usr/bin/java stub that reports no runtime. Homebrew
-    # installs the real one here, outside PATH.
-    HOMEBREW_JAVA = "/opt/homebrew/opt/openjdk/bin/java"
-    TIMEOUT_SECONDS = 300
-
-    module_function
-
-    # Download and unpack the pinned LanguageTool into DIR. Idempotent:
-    # returns the install directory, or nil after warning why. Pure Ruby
-    # throughout: the download uses Net::HTTP and the unpack uses rubyzip,
-    # so setup needs no curl or unzip on the machine.
-    def install(dir)
-      require "fileutils"
-      dest = File.join(dir, "LanguageTool-#{LT_VERSION}")
-      if File.exist?(File.join(dest, "languagetool-commandline.jar"))
-        remove_stale_versions(dir, dest)
-        return dest
-      end
-      zip = File.join(dir, "LanguageTool-#{LT_VERSION}.zip")
-      FileUtils.mkdir_p(dir)
-      return nil unless download(download_url, zip)
-      return nil unless extract(zip, dir)
-      File.delete(zip)
-      remove_stale_versions(dir, dest)
-      dest
-    end
-
-    def download_url
-      "https://languagetool.org/download/LanguageTool-#{LT_VERSION}.zip"
-    end
-
-    # Streams URL to TO and follows redirects. Warns and returns false
-    # on any transport or HTTP failure, so callers never see a stack
-    # trace.
-    def download(url, to, redirects: 3)
-      require "net/http"
-      uri = URI(url)
-      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-        open_timeout: 10, read_timeout: 60) do |http|
-        http.request(Net::HTTP::Get.new(uri)) do |response|
-          case response
-          when Net::HTTPRedirection
-            return false if redirects.zero?
-            return download(response["location"], to, redirects: redirects - 1)
-          when Net::HTTPSuccess
-            File.binwrite(to, "")
-            File.open(to, "wb") do |file|
-              response.read_body { |chunk| file.write(chunk) }
-            end
-            return true
-          else
-            warn "error: download failed: HTTP #{response.code} from #{url}"
-            return false
-          end
-        end
-      end
-    rescue SystemCallError, SocketError, Timeout::Error,
-      OpenSSL::SSL::SSLError, Net::ProtocolError => e
-      warn "error: download failed: #{e.class}: #{e.message}"
-      false
-    end
-
-    # Unpacks ZIP into DIR and refuses entries that try to escape it.
-    # Warns and returns false on any failure.
-    def extract(zip, dir)
-      require "zip"
-      Zip::File.open(zip) do |archive|
-        archive.each do |entry|
-          unless safe_entry_target(dir, entry.name)
-            warn "error: zip entry escapes the install dir: #{entry.name}"
-            return false
-          end
-          entry.extract(entry.name, destination_directory: dir,
-            create_parent_directories: true)
-        end
-      end
-      true
-    rescue SystemCallError, Zip::Error => e
-      warn "error: unpack failed: #{e.class}: #{e.message}"
-      false
-    end
-
-    # The path to write zip entry NAME into, or nil when NAME escapes
-    # DIR. A download is untrusted input: this is the zip-slip
-    # guard.
-    def safe_entry_target(dir, name)
-      target = File.expand_path(File.join(dir, name))
-      base = File.expand_path(dir) + File::SEPARATOR
-      target.start_with?(base) ? target : nil
-    end
-
-    # One gem version pins one LanguageTool version. Older dirs are
-    # hundreds of MB each, so delete them on every setup run and keep
-    # only the current version (and any zips: they are re-deleted or
-    # re-extracted by their own flow).
-    def remove_stale_versions(dir, keep)
-      require "fileutils"
-      Dir.glob(File.join(dir, "LanguageTool-*")).each do |entry|
-        FileUtils.rm_rf(entry) if File.directory?(entry) && entry != keep
-      end
-    end
-
-    # Proves the installation works end to end: java runs the
-    # commandline jar and the custom rules load. The command exits
-    # nonzero on a broken java, a corrupt jar, or invalid rules XML,
-    # so setup can report a real verdict instead of "files exist".
-    # Returns a boolean, never raises or warns: the caller owns the
-    # message.
-    def smoke(install)
-      rule = rule_ids.first
-      return false if rule.nil?
-      require "tmpdir"
-      Dir.mktmpdir do |dir|
-        text = File.join(dir, "smoke.txt")
-        File.write(text, "Check this sentence.\n")
-        system(install.java!, "-jar", install.commandline_jar,
-          "--language", "en", "--rulefile", RULES_FILE,
-          "--enable", rule, "--enabledonly", text,
-          out: File::NULL, err: File::NULL) ? true : false
-      end
-    end
-
-    def rule_ids
-      File.read(RULES_FILE).scan(/<rule(?:group)? id="(\w+)"/).flatten
-    end
-  end
-end

data/lib/simple_english/plain_text.rb

@@ -1,17 +0,0 @@
-# frozen_string_literal: true
-
-module SimpleEnglish
-  module Client
-    # 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
-
-      def locate(utf16_offset)
-        Client.offset_to_position(text, utf16_offset)
-      end
-    end
-  end
-end