simple_english 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18c24cb1079203715bb6c9decdf37cbae2221ef7db6ce93cc91cea6cd40e80ec
-  data.tar.gz: 25c81010ee8974bc23393acb0e7b692634616122201ca693e12a979ef310bf53
+  metadata.gz: 706801ef7861107694a40cc9671788179c54ea4ac4755491c92df1dd174da41b
+  data.tar.gz: 162d45ec0d0c979c855b49f8f639f0d679e5575f4b3e789453f3f01287feda63
 SHA512:
-  metadata.gz: 85550424bc3b8cbd339180ba2f1c91a3125690af0bebb8b11efdf4d367569b15952cff57122e3c768989d8233c4daa23eb4f8359e6a2ce20a1ba5b9471ef1f12
-  data.tar.gz: 7a51bf55350c8b34501c5a0537236890ab8783d1199cc8c57e84bd3f3d24107aafa2e8e2944e49e909601f5a33e5ed1f11cb9812e9f5bb500aea05e60bc6db3e
+  metadata.gz: 99b3510be0ae0327886b9cb8be7b4c008eaf8346091bf306423b5e2306c9896eea63d26c629b1a3b96cd2111d306834fedb368e7e1af3702bf5bf61bf3b1443a
+  data.tar.gz: 61840d3678edcc0e18a04db4c291935823a3d5aa139609ca5979a1b513c2420097645241aaa602cb5e2b009c31a1cc54da084f92641a0aba2795febefffe39dd

data/README.md

@@ -11,16 +11,18 @@ the slop it leaves behind. Every finding says what to write
 instead.
 
 ```console
-$ printf 'You should leverage this tool in order to make sure that your docs are readable.' > note.md
+$ printf "The config was written by setup — don't edit it; the daemon caches rules, making the first lint slow." > note.md
 $ se note.md
-note.md:1:5: [SE_MODAL_RESTRICTED] "should" - Use can, will, or must. State the requirement exactly.
-note.md:1:12: [SE_SLOP_LEVERAGE] "leverage" - Write "use".
-note.md:1:31: [SE_SLOP_IN_ORDER_TO] "in order to" - Write "to".
+note.md:1:12-26: [SE_ACTIVE_VOICE] "was written by" - Use the active voice. Say who does the action.
+note.md:1:73-81: [SE_ING_AFTER_COMMA] ", making" - Start a new sentence instead of the -ing phrase.
+note.md:1:37-40: [SE_NO_CONTRACTIONS] "n't" - Write the words in full. No contractions.
+note.md:1:33-34: [SE_NO_EMDASH] "—" - Write two sentences, or use a comma.
+note.md:1:48-49: [SE_NO_SEMICOLON] ";" - Write two sentences, or name the relation.
 ```
 
 Markdown prose plus code comments in Python, Ruby, JavaScript,
-TypeScript, Go, Rust, Java, C#, Kotlin, bash, and YAML. Output as plain
-text, JSON, or SARIF.
+TypeScript, Go, Rust, Java, C#, C++, Kotlin, bash, and YAML. Output as
+plain text, JSON, or SARIF.
 
 ## The rules
 
@@ -31,7 +33,7 @@ text, JSON, or SARIF.
 - **Contractions:** write every word in full.
 - **Sentence shape:** condition before command, no `-ing` phrase after a comma.
 - **Word choice:** about 50 substitution rules, from `leverage` to `in conclusion`. `make sure that` keeps its "that".
-- **Code comments:** same pattern rules, with line and column.
+- **Code comments:** same pattern rules, with line and column range.
 - **Counts (Markdown only):** 20 words per sentence in list items, 25 in paragraphs, six sentences per paragraph at most.
 
 The full list, with a wrong and a right example for each rule:
@@ -39,10 +41,23 @@ The full list, with a wrong and a right example for each rule:
 
 ## Install
 
-**Requirements:** Ruby 3.3 or newer, Java 11 or newer for
+**Requirements:** On macOS, Homebrew covers everything. On Linux,
+Windows, or CI, you need Ruby 3.3 or newer and Java 11 or newer for
 LanguageTool. The Docker image bundles both.
 
-### Ruby gem
+### Homebrew (macOS)
+
+```bash
+brew install TonyCTHsu/tap/simple-english
+brew services start simple-english
+```
+
+Homebrew installs Ruby and Java alongside, so the machine needs
+neither. The service keeps a background daemon running. Its first
+start downloads LanguageTool (about 300 MB), and later lints take
+milliseconds. Run `brew services stop simple-english` to stop it.
+
+### Ruby gem (Linux, Windows, CI)
 
 ```bash
 gem install simple_english
@@ -50,10 +65,7 @@ se setup    # run once: downloads LanguageTool, locates Java, verifies both
 se README.md
 ```
 
-`se setup` puts LanguageTool into `~/.cache/se` and touches nothing
-in your shell profile. Pass `--dir PATH` or set `SE_CACHE_DIR` to
-put the cache somewhere else. If `java` is not on PATH, set `SE_JAVA`
-to your java binary.
+If `java` is not on PATH, set `SE_JAVA` to your java binary.
 
 ### Container
 
@@ -63,13 +75,6 @@ The image holds Ruby, Java, and LanguageTool, so it needs no setup:
 docker run -v "$PWD":/work ghcr.io/tonycthsu/simple-english:latest docs/
 ```
 
-Or keep the daemon in a container and lint through it:
-
-```bash
-docker run -d --name se-daemon -p 8181:8181 ghcr.io/tonycthsu/simple-english:latest serve
-SE_SERVER_URL=http://localhost:8181 se lint docs/
-```
-
 ### Git repository
 
 Run `bundle install`, then use `bin/se`.
@@ -88,12 +93,16 @@ se - < notes.md     # stdin (Markdown)
 Lint only what changed:
 
 ```bash
-git diff --name-only --diff-filter=ACM main | xargs se
+git diff --name-only --diff-filter=ACM main | xargs -I{} se {}
 ```
 
 ### Outputs
 
-Findings print as `file:line: [RULE_ID] message`. Code-comment findings also carry a column in `--format json` and `--format sarif`:
+Pattern findings print an exclusive column range as
+`file:line:start-end: [RULE_ID] message`. A range that crosses lines ends
+with `end-line:end-column`. Columns count UTF-16 code units. Counting findings
+identify only the paragraph's first line. JSON and SARIF output expose the same
+source ranges:
 
 ```bash
 se --format json docs/
@@ -108,7 +117,7 @@ se --format sarif src/ > results.sarif
 
 ### CI
 
-Gate the docs in the pull request that changes them. The plain run
+Gate the prose in the pull request that changes it. The plain run
 fails the build on findings, and the SARIF report puts them inline:
 
 ```yaml
@@ -166,24 +175,16 @@ In a code comment:
 # Don't touch this constant. se: ignore=SE_NO_CONTRACTIONS
 ```
 
-## The daemon
+## The background daemon
 
-The first lint starts the daemon automatically (about 15 seconds
-once, then you need Java and one run of `se setup`). Later lints hit
-the running daemon and take milliseconds. To start it ahead of time:
+The CLI runs a small background server on your machine. The first
+lint starts it, which takes about 15 seconds. Later lints take
+milliseconds.
 
-```bash
-se serve --port 8181 &
-```
-
-Any tool or language can lint through its HTTP API:
-
-```bash
-curl -d "text=Don't do this." http://localhost:8181/lint
-# [{"line":1,"column":null,"rule":"SE_NO_CONTRACTIONS","message":"..."}]
-```
-
-The full wire format: [docs/DAEMON.md](docs/DAEMON.md).
+The first lint after a gem update prints a warning. Run `se serve --detached` then.
+It stops the old daemon and starts the new one in the
+background. You never talk to the daemon directly. Its HTTP
+interface is internal and can change in any release.
 
 ## Scope
 
@@ -192,6 +193,27 @@ SimpleEnglish project. This tool does not check ASD-STE100 compliance.
 This repo holds no ASD-STE100 text. If you need full compliance, read
 the free standard at <https://www.asd-ste100.org/>.
 
+## FAQ
+
+### Have you thought about an agent skill?
+
+The [SimpleEnglish project](https://github.com/AminBlg/SimpleEnglish)
+ships one. Its skill guides an agent while it writes. This tool does
+the other half of the work. It checks the result against fixed
+rules. Use both: the skill helps the first draft, and the linter
+catches what the agent missed.
+
+### Why not Vale?
+
+We ported all 67 rules to Vale and ran the corpus on both engines.
+About 60 rules behave the same. Vale has no check for the em-dash
+and semicolon rules: its checks see words, not punctuation. Its
+tagger also mislabels verbs, so the condition-first rule stays
+silent. The rules here are LanguageTool XML with examples that CI
+verifies. Closing the Vale gaps needs scripts or an external
+tagger, and that erases Vale's main advantage: one binary with no
+service behind it.
+
 ## Develop
 
 To change the linter, add rules, or run the tests, read [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md).

data/docs/RULES.md

@@ -2,7 +2,7 @@
 
 Generated by `bin/render-rules`. Do not edit by hand. The source
 of truth is `rules/simple-english.xml` and
-`lib/simple_english/counts.rb`.
+`lib/simple_english/lint/counts.rb`.
 
 ## Pattern rules
 

data/lib/simple_english/cli.rb

@@ -28,6 +28,10 @@ module SimpleEnglish
       start(argv)
     end
 
+    # How each Install.java_source found its java, for `se setup`'s
+    # report line.
+    JAVA_SOURCES = {env: "SE_JAVA", path: "PATH", homebrew: "Homebrew fallback"}.freeze
+
     default_task :lint
     desc "lint FILE_OR_DIR...", "Lint Markdown prose and code comments (- reads stdin)"
     method_option :format, type: :string, default: "text", enum: %w[text json sarif],
@@ -62,43 +66,62 @@ module SimpleEnglish
       results.empty? ? 0 : 1
     end
 
+    desc "version", "Print the gem version. The container image tag is v plus this."
+    def version
+      puts SimpleEnglish::VERSION
+      0
+    end
+
     desc "serve", "Run the lint daemon in the foreground"
     method_option :port, type: :numeric, default: SimpleEnglish::Client::DEFAULT_PORT,
       desc: "Port to listen on"
     method_option :"dev-log", type: :string, banner: "PATH",
       desc: "Write daemon stderr to PATH"
+    method_option :detached, type: :boolean,
+      desc: "Replace any running se daemon and run in the background"
     def serve
+      if options[:detached]
+        daemon = SimpleEnglish::Server.start_detached(port: options[:port],
+          install: SimpleEnglish::Install.from_env, dev_log: options[:"dev-log"])
+        if daemon
+          puts "se daemon detached, pid #{daemon["pid"]}, " \
+            "on http://localhost:#{options[:port]}"
+          return 0
+        end
+        warn "error: detached daemon did not come up. " \
+          "Run `se serve` and read its output."
+        return 2
+      end
       log = options[:"dev-log"] ? File.open(options[:"dev-log"], "w") : $stderr
       SimpleEnglish::Server.start(port: options[:port],
         install: SimpleEnglish::Install.from_env, log: log)
       0
-    rescue SimpleEnglish::Install::SetupError, SimpleEnglish::Server::ServerError => e
+    rescue SimpleEnglish::Install::SetupError, SimpleEnglish::Server::ServerError,
+      SimpleEnglish::Config::ConfigError => e
       warn "error: #{e.message}"
       2
     end
 
     desc "setup", "Download LanguageTool and locate Java. Idempotent."
-    method_option :dir, type: :string, banner: "PATH",
-      desc: "Install into PATH (default: the shared cache)"
     def setup
       install = SimpleEnglish::Install.from_env
-      lt_dir = SimpleEnglish::LanguageTool.install(options[:dir] || install.cache_dir)
-      return 2 unless lt_dir
+      lt = SimpleEnglish::LanguageTool.install(install.cache_dir)
+      return 2 unless lt
+      puts "LanguageTool #{SimpleEnglish::LanguageTool::LT_VERSION}: " \
+        "#{lt["downloaded"] ? "downloaded to" : "already present at"} #{lt["dir"]}"
       unless install.java?
-        warn "error: java not found. Install a JRE (on macOS: brew install openjdk), " \
-          "or set SE_JAVA to your java binary."
+        warn "error: #{install.java_message}"
         return 2
       end
+      puts "Java: #{install.java} (#{JAVA_SOURCES[install.java_source]})"
       unless SimpleEnglish::LanguageTool.smoke(install)
         warn "error: LanguageTool smoke test failed. The download may be corrupt. " \
-          "Delete #{lt_dir} and rerun `se setup`."
+          "Delete #{lt["dir"]} and rerun `se setup`."
         return 2
       end
-      puts <<~SETUP
-        LanguageTool #{SimpleEnglish::LanguageTool::LT_VERSION} is at #{lt_dir}
-
-        se finds it there automatically. Nothing to export.
-      SETUP
+      puts "Smoke test: passed"
+      puts
+      puts "se finds them automatically. Nothing to export."
       0
     end
 
@@ -122,6 +145,7 @@ module SimpleEnglish
       when "json"
         puts JSON.pretty_generate(results.map do |path, finding|
           {"path" => path, "line" => finding.line, "column" => finding.column,
+           "end_line" => finding.end_line, "end_column" => finding.end_column,
            "rule" => finding.rule, "message" => finding.message}
         end)
       when "sarif"
@@ -129,10 +153,17 @@ module SimpleEnglish
           "version" => "2.1.0",
           "$schema" => "https://json.schemastore.org/sarif-2.1.0.json",
           "runs" => [{
+            "columnKind" => "utf16CodeUnits",
             "tool" => {"driver" => {"name" => "se"}},
             "results" => results.map do |path, finding|
               region = {"startLine" => finding.line}
-              region["startColumn"] = finding.column if finding.column
+              if finding.column
+                region["startColumn"] = finding.column
+                if finding.end_line && finding.end_column
+                  region["endLine"] = finding.end_line
+                  region["endColumn"] = finding.end_column
+                end
+              end
               {"ruleId" => finding.rule, "level" => "error",
                "message" => {"text" => finding.message},
                "locations" => [{"physicalLocation" => {
@@ -145,7 +176,14 @@ module SimpleEnglish
       else
         results.each do |path, finding|
           location = "#{path}:#{finding.line}"
-          location << ":#{finding.column}" if finding.column
+          if finding.column
+            location += ":#{finding.column}"
+            if finding.end_line && finding.end_column
+              finish = (finding.end_line == finding.line) ? finding.end_column :
+                "#{finding.end_line}:#{finding.end_column}"
+              location += "-#{finish}"
+            end
+          end
           puts "#{location}: [#{finding.rule}] #{finding.message}"
         end
       end

data/lib/simple_english/client/daemon.rb

@@ -0,0 +1,225 @@
+# 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
+
+    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 `se 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 File.exist?(install.server_jar) && install.java?
+        warn(install.java? ? install.setup_error : install.java_message)
+        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 takes ~15s)..."
+          spawn_daemon
+          daemon = wait_for { info }
+        end
+        if daemon
+          check_daemon(daemon)
+        else
+          warn "error: se daemon did not come up. Run `se 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 `se 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, independent of the
+    # installation cache: daemon ownership is scoped to the port,
+    # so two lints with different SE_CACHE_DIR values still
+    # coordinate. 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 JVM) 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