simple_english 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c05cc78b762e2b44f4c841ef5a78537e91d9bcd408ed8739fcc00f3538f14eb
-  data.tar.gz: 9abac46821a9260b3ec7312a1c258464e08a943262eaccab893383104479dcee
+  metadata.gz: 18c24cb1079203715bb6c9decdf37cbae2221ef7db6ce93cc91cea6cd40e80ec
+  data.tar.gz: 25c81010ee8974bc23393acb0e7b692634616122201ca693e12a979ef310bf53
 SHA512:
-  metadata.gz: 6c4ac5c79f9a62c848ae37977dfb48ec2b815b27e5a38af7ab448a489206b14b8b26dec4f560b5115dd5be3c3688bfed254ebecbfd5e57c83c84d4a545367780
-  data.tar.gz: 699067a5a056a54186fe40d62ee17dd358492409dd86a76fc17cd2e1be8d110ee1147daa3ecb5f4d8b995cfd98f4108e96adbf6ed96603a43566ee820fd48729
+  metadata.gz: 85550424bc3b8cbd339180ba2f1c91a3125690af0bebb8b11efdf4d367569b15952cff57122e3c768989d8233c4daa23eb4f8359e6a2ce20a1ba5b9471ef1f12
+  data.tar.gz: 7a51bf55350c8b34501c5a0537236890ab8783d1199cc8c57e84bd3f3d24107aafa2e8e2944e49e909601f5a33e5ed1f11cb9812e9f5bb500aea05e60bc6db3e

data/README.md

@@ -1,3 +1,7 @@
+[![CI](https://github.com/TonyCTHsu/simple-english/actions/workflows/ci.yml/badge.svg)](https://github.com/TonyCTHsu/simple-english/actions/workflows/ci.yml) <!-- se: ignore=SE_PARAGRAPH_TOO_LONG -->
+[![Gem Version](https://badge.fury.io/rb/simple_english.svg)](https://badge.fury.io/rb/simple_english)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/TonyCTHsu/simple-english/blob/master/LICENSE)
+
 # simple_english
 
 > Write for human readers, not for reviewers or another AI.
@@ -9,9 +13,9 @@ instead.
 ```console
 $ printf 'You should leverage this tool in order to make sure that your docs are readable.' > note.md
 $ se note.md
-note.md:1: [SE_MODAL_RESTRICTED] Use can, will, or must. State the requirement exactly.
-note.md:1: [SE_SLOP_IN_ORDER_TO] Write "to".
-note.md:1: [SE_SLOP_LEVERAGE] Write "use".
+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".
 ```
 
 Markdown prose plus code comments in Python, Ruby, JavaScript,

data/lib/simple_english/cli.rb

@@ -144,7 +144,9 @@ module SimpleEnglish
         )
       else
         results.each do |path, finding|
-          puts "#{path}:#{finding.line}: [#{finding.rule}] #{finding.message}"
+          location = "#{path}:#{finding.line}"
+          location << ":#{finding.column}" if finding.column
+          puts "#{location}: [#{finding.rule}] #{finding.message}"
         end
       end
     end

data/lib/simple_english/client.rb

@@ -29,6 +29,26 @@ module SimpleEnglish
       line
     end
 
+    # The 1-based column of a UTF-16 offset within its line. Astral
+    # characters count as two units, like the match offset. A match
+    # starting at the newline itself is column one of the next line.
+    def offset_to_column(text, offset)
+      column = 0
+      units = 0
+      text.each_char do |char|
+        if char == "\n"
+          return 1 if units >= offset
+          column = 0
+          units += 1
+          next
+        end
+        return column + 1 if units >= offset
+        units += (char.ord > 0xFFFF) ? 2 : 1
+        column += 1
+      end
+      column + 1
+    end
+
     DEFAULT_PORT = 8181
     REQUEST_TIMEOUT = 30
 
@@ -64,15 +84,27 @@ module SimpleEnglish
       matches.map do |match|
         line, column = payload.locate(match.fetch("offset"))
         Finding.new(line: line, column: column,
-          rule: match.fetch("rule").fetch("id"), message: match.fetch("message"))
+          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. LanguageTool returns it in the match context.
+    # Context offsets are Java UTF-16 code units, like the match
+    # offset.
+    def with_context(message, match)
+      context = match["context"] or return message
+      matched = context.fetch("text", "")[
+        context.fetch("offset", 0).to_i, context.fetch("length", 0).to_i]
+      matched.empty? ? message : "\"#{matched}\" - #{message}"
+    end
+
     def to_payload(payload)
       payload.is_a?(String) ? PlainText.new(payload) : payload
     end
 
-    private_class_method :to_payload
+    private_class_method :to_payload, :with_context
 
     # Full lint via the se daemon. Raw Markdown in, or code
     # source with a language for the comment pipeline. nil when
@@ -109,15 +141,15 @@ module SimpleEnglish
     # caller owns the exit status. Diagnostics go to stderr here, where the cause
     # is known.
     def ensure_up(install: SimpleEnglish::Install.from_env)
-      unless File.exist?(install.server_jar)
-        warn install.setup_error
-        return false
-      end
       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)

data/lib/simple_english/markdown.rb

@@ -9,7 +9,10 @@ require_relative "paragraph"
 
 module SimpleEnglish
   module Markdown
-    SENTENCE_END = /[.!?]/
+    # A terminator ends a sentence only before whitespace or at the
+    # end of the text, so periods inside URLs and file names do not
+    # split sentences.
+    SENTENCE_END = /(?<=[.!?])(?:\s+|$)/
     # Non-prose blocks: their lines never reach the counting rules or
     # LanguageTool.
     BLANKED_BLOCKS = %w[fenced_code_block indented_code_block thematic_break].freeze
@@ -27,7 +30,10 @@ module SimpleEnglish
     end
 
     def strip_line(line)
-      line.gsub(/`[^`]*`/, "X").sub(/\A\#{1,6} /, "")
+      # Width-preserving replacements, so a finding column points at
+      # the source line, not at the stripped copy.
+      line.gsub(/`[^`]*`/) { |code| "X" * code.length }
+        .sub(/\A\#{1,6} /) { |marker| " " * marker.length }
     end
 
     # A vertical list is not one paragraph: each list item is its own.

data/lib/simple_english/plain_text.rb

@@ -10,7 +10,8 @@ module SimpleEnglish
       end
 
       def locate(utf16_offset)
-        [Client.offset_to_line(text, utf16_offset), nil]
+        [Client.offset_to_line(text, utf16_offset),
+          Client.offset_to_column(text, utf16_offset)]
       end
     end
   end

data/lib/simple_english/server.rb

@@ -59,10 +59,12 @@ module SimpleEnglish
       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. The dev log has a path. $stderr does not, so fall
-      # back to a temp file that Ruby unlinks when the process exits.
+      # its first line. Only an explicitly opened dev log (a File) is reused
+      # for that. $stderr reports path "<STDERR>", so it creates a file
+      # by that name in the CWD. Anything else falls back to a temp file
+      # that Ruby unlinks when the process exits.
       inner_log_path =
-        if log.respond_to?(:path)
+        if log.is_a?(File)
           log.path
         else
           inner_log = Tempfile.new("se-inner")

data/lib/simple_english/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  VERSION = "0.2.0"
+end

data/lib/simple_english.rb

@@ -4,6 +4,7 @@
 # Pattern rules run on LanguageTool. Counting rules run here.
 # This file is the composition root. The pieces live in lib/simple_english/.
 
+require_relative "simple_english/version"
 require_relative "simple_english/finding"
 require_relative "simple_english/markdown"
 require_relative "simple_english/counts"
@@ -19,8 +20,6 @@ require_relative "simple_english/client"
 require_relative "simple_english/server"
 
 module SimpleEnglish
-  VERSION = "0.1.0"
-
   module_function
 
   # Returns findings, or nil when the daemon is unreachable. The

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_english
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - TonyCTHsu
@@ -72,14 +72,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-mock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.27'
 - !ruby/object:Gem::Dependency
   name: json
   requirement: !ruby/object:Gem::Requirement
@@ -140,6 +154,7 @@ files:
 - lib/simple_english/server.rb
 - lib/simple_english/span.rb
 - lib/simple_english/suppressions.rb
+- lib/simple_english/version.rb
 - rules/simple-english.xml
 homepage: https://github.com/TonyCTHsu/simple-english
 licenses: