simple_english 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c05cc78b762e2b44f4c841ef5a78537e91d9bcd408ed8739fcc00f3538f14eb
-  data.tar.gz: 9abac46821a9260b3ec7312a1c258464e08a943262eaccab893383104479dcee
+  metadata.gz: 5c1efe5da86f44ce1618aea7d2c49f3e5dd0aec897a8f103ace5276be73d9ef4
+  data.tar.gz: cd8597b07d037a0631d16ea11377144fb9b93d6f6e604a316027d5c43a72d50d
 SHA512:
-  metadata.gz: 6c4ac5c79f9a62c848ae37977dfb48ec2b815b27e5a38af7ab448a489206b14b8b26dec4f560b5115dd5be3c3688bfed254ebecbfd5e57c83c84d4a545367780
-  data.tar.gz: 699067a5a056a54186fe40d62ee17dd358492409dd86a76fc17cd2e1be8d110ee1147daa3ecb5f4d8b995cfd98f4108e96adbf6ed96603a43566ee820fd48729
+  metadata.gz: 838420d06071034d7e6d48c074fc0d5893b6443e6f1dd387247e86239f74b620ff7e4adecd69e4b37a3d58e98ebb193bbe53a113dc96759a075cb08fdd8247c7
+  data.tar.gz: 7fcc415dcf6cc5a01ba01807118ca6e3ea8ff7f7d4573960f5b31fe7971c3612559e15d5f7ee0c122363cdf2b620b8ede79ed7b0e0e193dd188a0446483045fc

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.
@@ -7,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: [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: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
 
@@ -27,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:
@@ -89,7 +95,11 @@ git diff --name-only --diff-filter=ACM main | xargs 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/
@@ -176,7 +186,7 @@ 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":"..."}]
+# [{"line":1,"column":3,"end_line":1,"end_column":6,"rule":"SE_NO_CONTRACTIONS","message":"..."}]
 ```
 
 The full wire format: [docs/DAEMON.md](docs/DAEMON.md).

data/lib/simple_english/cli.rb

@@ -122,6 +122,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 +130,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" => {
@@ -144,7 +152,16 @@ module SimpleEnglish
         )
       else
         results.each do |path, finding|
-          puts "#{path}:#{finding.line}: [#{finding.rule}] #{finding.message}"
+          location = "#{path}:#{finding.line}"
+          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
     end

data/lib/simple_english/client.rb

@@ -14,19 +14,23 @@ module SimpleEnglish
   module Client
     module_function
 
-    # LanguageTool reports offsets in Java UTF-16 code units.
-    # Astral characters (emoji) count as two. Count them so a
-    # newline comparison cannot drift past a boundary. A match
-    # starting at the newline itself belongs to the next line.
-    def offset_to_line(text, offset)
+    # 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|
-        line += 1 if char == "\n" && units <= offset
-        return line if units >= offset
+        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
+      [line, column]
     end
 
     DEFAULT_PORT = 8181
@@ -62,17 +66,45 @@ module SimpleEnglish
     def parse_matches(matches, payload)
       payload = to_payload(payload)
       matches.map do |match|
-        line, column = payload.locate(match.fetch("offset"))
+        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,
-          rule: match.fetch("rule").fetch("id"), message: match.fetch("message"))
+          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
+    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
@@ -87,6 +119,7 @@ module SimpleEnglish
       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,
@@ -109,15 +142,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/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/finding.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
-# One lint result. The line and column are 1-based. The column is
-# nil when the rule has no position within the line.
+# 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, :rule, :message)
+  Finding = Struct.new(:line, :column, :end_line, :end_column, :rule, :message)
 end

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
@@ -18,16 +21,37 @@ 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)
-      line.gsub(/`[^`]*`/, "X").sub(/\A\#{1,6} /, "")
+      # 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.
@@ -91,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/plain_text.rb

@@ -10,7 +10,7 @@ module SimpleEnglish
       end
 
       def locate(utf16_offset)
-        [Client.offset_to_line(text, utf16_offset), nil]
+        Client.offset_to_position(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.3.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

data/rules/simple-english.xml

@@ -56,10 +56,14 @@
     </rule>
 
     <rule id="SE_ING_AFTER_COMMA" name="No -ing after a comma">
-      <pattern><token>,</token><token postag="VBG"/></pattern>
+      <pattern><token>,</token><token postag="VBG"><exception scope="next" regexp="yes">[,)]|and|or</exception></token></pattern>
       <message>Start a new sentence instead of the -ing phrase.</message>
       <example type="incorrect">The tool runs<marker>, making</marker> it easy.</example>
       <example type="correct">The tool runs. It is easy.</example>
+      <example type="correct">The walkthrough (accounts, VPC, secrets, troubleshooting) is in the guide.</example>
+      <example type="correct">The guide covers billing, troubleshooting, and support for each environment.</example>
+      <example type="correct">The guide covers billing, troubleshooting and support for each environment.</example>
+      <example type="correct">The guide covers billing, troubleshooting or support for each environment.</example>
     </rule>
 
     <rule id="SE_KEEP_THAT" name="make sure that">

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_english
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - TonyCTHsu
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-28 00:00:00.000000000 Z
+date: 2026-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tree_sitter_language_pack
@@ -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,11 +154,15 @@ 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:
 - MIT
-metadata: {}
+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
 post_install_message:
 rdoc_options: []
 require_paths: