simple_english 0.6.0-x86_64-linux

data/lib/simple_english/lint/plain_text.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  # 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
+
+    # LanguageTool reports offsets in Java UTF-16 code units.
+    # Return a 1-based line and UTF-16 column for a 0-based offset.
+    def locate(utf16_offset)
+      line = 1
+      column = 1
+      units = 0
+      text.each_char do |char|
+        return [line, column] if units >= utf16_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
+  end
+end

data/lib/simple_english/lint/result.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  module AnnotatedText
+    # The payload for code comments. Duck interface shared with
+    # PlainText: #lt_params (the form data for LanguageTool)
+    # and #locate (a match offset back to file line and column).
+    Result = Struct.new(:source, :segments, :stream) do
+      def lt_params
+        {"data" => SimpleEnglish::AnnotatedText.data_json(self)}
+      end
+
+      def locate(utf16_offset)
+        SimpleEnglish::AnnotatedText.locate(self, utf16_offset)
+      end
+    end
+  end
+end

data/lib/simple_english/lint/segment.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  module AnnotatedText
+    # One piece of the annotation stream: checkable comment text or
+    # uncheckable markup (markers, closers, gaps between comments).
+    # stream_start is the segment's offset into Result#stream.
+    Segment = Struct.new(:text, :content, :file_char, :stream_start,
+      :interpret_as)
+  end
+end

data/lib/simple_english/lint/span.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SimpleEnglish
+  module Extractor
+    # One comment: its text and byte range in the source file.
+    Span = Struct.new(:text, :start_byte, :end_byte)
+  end
+end

data/lib/simple_english/lint/suppressions.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Inline suppressions. A line containing `se: ignore` (or
+# `se: ignore=RULE1,RULE2`) suppresses findings reported on that
+# same line. Pattern findings cite the line of the match, not the
+# paragraph or comment start, so put the directive on the line the
+# finding reports.
+
+module SimpleEnglish
+  module Suppressions
+    DIRECTIVE = /se:\s*ignore\s*(?:=\s*(?<rules>[\w,]+))?/
+
+    module_function
+
+    def filter(source, findings)
+      return findings if findings.empty?
+      blocked = directives(source)
+      return findings if blocked.empty?
+      findings.reject do |finding|
+        blocked.any? do |directive|
+          directive[:line] == finding.line &&
+            (directive[:rules].empty? || directive[:rules].include?(finding.rule))
+        end
+      end
+    end
+
+    def directives(source)
+      source.lines.each_with_index.filter_map do |line, index|
+        next unless (match = line.match(DIRECTIVE))
+        rules = match[:rules] ? match[:rules].split(",").map(&:strip) : []
+        {line: index + 1, rules: rules}
+      end
+    end
+
+    private_class_method :directives
+  end
+end

data/lib/simple_english/model_context_protocol.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require "json"
+
+# MCP JSON-RPC server for the lint engine. `respond` is pure: request
+# Hash in, response Hash or nil (notifications) out. `run` drives it
+# over stdio, one JSON-RPC message per line. Protocol facts:
+# integrations/verification.md.
+
+module SimpleEnglish
+  module ModelContextProtocol
+    SUPPORTED_VERSIONS = ["2025-06-18", "2025-03-26", "2024-11-05"].freeze
+    LATEST_VERSION = "2025-06-18"
+    SERVER_NAME = "simple-english"
+
+    module_function
+
+    def run(io: $stdin, out: $stdout, linter: method(:default_linter))
+      # A piped stdout buffers until 4 KB or EOF. An MCP client keeps
+      # stdin open while it waits for the answer, so an unflushed
+      # response never arrives and the client drops the server.
+      out.sync = true
+      while (line = io.gets)
+        line = line.strip
+        next if line.empty?
+        begin
+          request = JSON.parse(line)
+        rescue JSON::ParserError
+          next
+        end
+        next unless request.is_a?(Hash)
+        response =
+          begin
+            respond(request, linter: linter)
+          rescue => e
+            # A broken tool call (unreadable file, daemon hiccup) must not
+            # kill the loop: answer it, then serve the next line.
+            request.key?("id") ? error(request["id"], -32603, "lint failed: #{e.class}: #{e.message}") : nil
+          end
+        out.puts JSON.generate(response) if response
+      end
+    end
+
+    # The CLI's lint pipeline as a callable: .simple-english.yml decides
+    # which paths and rules count, then the daemon lints the file.
+    def default_linter(path)
+      config = SimpleEnglish::Config.load
+      return [] if SimpleEnglish::Config.ignore?(config, path)
+      findings = SimpleEnglish.lint_file(path)
+      findings.nil? ? nil : SimpleEnglish::Config.filter(config, path, findings)
+    end
+
+    def respond(request, linter:)
+      return nil unless request.key?("id")
+      id = request.fetch("id")
+      method = request["method"]
+      return error(id, -32600, "Invalid Request") unless method.is_a?(String)
+      params = request["params"]
+      params = {} unless params.is_a?(Hash)
+      case method
+      when "initialize" then ok(id, initialize_result(params["protocolVersion"]))
+      when "tools/list" then ok(id, {"tools" => [lint_tool]})
+      when "tools/call" then tools_call(id, params, linter)
+      else error(id, -32601, "Method not found: #{method}")
+      end
+    end
+
+    def initialize_result(requested_version)
+      version = SUPPORTED_VERSIONS.include?(requested_version) ? requested_version : LATEST_VERSION
+      {
+        "protocolVersion" => version,
+        "capabilities" => {"tools" => {}},
+        "serverInfo" => {"name" => SERVER_NAME, "version" => SimpleEnglish::VERSION}
+      }
+    end
+
+    def lint_tool
+      {
+        "name" => "lint",
+        "description" =>
+          "Lint Markdown prose and code comments against plain-English rules " \
+          "(short sentences, active voice, no jargon, no filler). " \
+          "Input: a file path. Returns one line per finding, or 'clean' when " \
+          "nothing is flagged. Fix the findings, then call again until clean.",
+        "inputSchema" => {
+          "type" => "object",
+          "properties" => {"path" => {"type" => "string", "description" => "File to lint"}},
+          "required" => ["path"]
+        }
+      }
+    end
+
+    def tools_call(id, params, linter)
+      tool = params["name"]
+      return error(id, -32602, "Unknown tool: #{tool}") unless tool == "lint"
+      arguments = params["arguments"]
+      arguments = {} unless arguments.is_a?(Hash)
+      path = arguments["path"]
+      return ok(id, tool_error("the path argument is required.")) if path.nil? || path.to_s.empty?
+      return ok(id, tool_error("#{path} is a directory. Give one file.")) if File.directory?(path)
+      return ok(id, tool_error("file not found: #{path}")) unless File.exist?(path)
+      findings =
+        begin
+          linter.call(path)
+        rescue SimpleEnglish::Config::ConfigError => e
+          return ok(id, tool_error("invalid .simple-english.yml: #{e.message}"))
+        end
+      if findings.nil?
+        # A tool error, not a protocol error: clients show the text to the
+        # model, and this message is the one that tells it how to recover.
+        ok(id, tool_error("the se daemon did not answer. Run `se serve --detached` and retry."))
+      else
+        ok(id, {"content" => [{"type" => "text", "text" => render(path, findings)}], "isError" => false})
+      end
+    end
+
+    def render(path, findings)
+      return "clean" if findings.empty?
+      findings.map { |finding| finding.to_line(path) }.join("\n")
+    end
+
+    def tool_error(text)
+      {"content" => [{"type" => "text", "text" => text}], "isError" => true}
+    end
+
+    def ok(id, result)
+      {"jsonrpc" => "2.0", "id" => id, "result" => result}
+    end
+
+    def error(id, code, message)
+      {"jsonrpc" => "2.0", "id" => id, "error" => {"code" => code, "message" => message}}
+    end
+  end
+end

data/lib/simple_english/setup/config.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# .simple-english.yml: ignore (path globs, matched against the paths
+# given on the command line) and disabled-rules (rule IDs dropped
+# from every file). Loaded from the CWD.
+
+module SimpleEnglish
+  module Config
+    ConfigError = Class.new(StandardError)
+    DEFAULT = {ignore: [], disabled_rules: []}.freeze
+
+    module_function
+
+    def load(dir = Dir.pwd)
+      file = File.join(dir, ".simple-english.yml")
+      return DEFAULT unless File.exist?(file)
+      require "yaml"
+      data = YAML.safe_load_file(file) || {}
+      {ignore: Array(data["ignore"]),
+       disabled_rules: Array(data["disabled-rules"])}
+    rescue Psych::SyntaxError => e
+      raise ConfigError, ".simple-english.yml: #{e.message}"
+    end
+
+    # Hooks pass absolute paths while ignore globs are written
+    # relative to the repo root (the CWD). Match both forms.
+    # realpath because CWD may be a symlink-resolved path while the
+    # caller's string still carries the symlink (TMPDIR on macOS).
+    def ignore?(config, path)
+      candidates = [path, relative_candidate(path)].compact
+      candidates.any? { |candidate| config[:ignore].any? { |pattern| matches?(pattern, candidate) } }
+    end
+
+    def relative_candidate(path)
+      pwd = Dir.pwd + "/"
+      resolved = File.exist?(path) ? File.realpath(path) : File.expand_path(path)
+      resolved.start_with?(pwd) ? resolved.delete_prefix(pwd) : nil
+    end
+
+    # File.fnmatch has no globstar: `**` never crosses directories.
+    # Translate instead: `**` as a whole segment is any depth, `*` and
+    # `?` stay within one segment.
+    def matches?(pattern, path)
+      glob_to_regex(pattern).match?(path)
+    end
+
+    def glob_to_regex(pattern)
+      Regexp.new("\\A" + pattern.split("/").map do |segment|
+        if segment == "**"
+          "(?:[^/]+/)*[^/]*"
+        else
+          Regexp.escape(segment).gsub("\\*", "[^/]*").gsub("\\?", "[^/]")
+        end
+      end.join("/") + "\\z")
+    end
+
+    def filter(config, path, findings)
+      return [] if ignore?(config, path)
+      disabled = config[:disabled_rules]
+      findings.reject { |finding| disabled.include?(finding.rule) }
+    end
+  end
+end

data/lib/simple_english/setup/fingerprint.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# Fingerprints for the daemon handshake. `gem` identifies the code and
+# built-in rules a daemon runs: any release that changes lint behavior
+# changes it, and nothing else does. `sha` covers the staged rule
+# content wherever the caller resolved it.
+
+require_relative "languagetool"
+
+module SimpleEnglish
+  module Fingerprint
+    module_function
+
+    # Hash everything the daemon can execute, not a curated list: a
+    # curated list goes stale the first time a new file is forgotten,
+    # and a missed file means silent staleness, the exact bug the
+    # handshake exists to catch. The accepted cost: a release that
+    # only changes caller-side code triggers one needless restart.
+    # ponytail: whole-lib glob. If restarts ever hurt, curate per-file.
+    def gem
+      files = Dir.glob(File.expand_path("../../**/*.rb", __dir__)).sort
+      files << LanguageTool::RULES_FILE
+      # Each file is length-prefixed: bare concatenation cannot tell
+      # ["ab", "c"] from ["a", "bc"], so bytes moved across a file
+      # boundary leave the digest unchanged.
+      framed = files.map do |path|
+        content = File.read(path)
+        "#{content.bytesize}\n#{content}"
+      end
+      sha(framed.join)
+    end
+
+    def sha(content)
+      require "digest"
+      ::Digest::SHA256.hexdigest(content)
+    end
+  end
+end

data/lib/simple_english/setup/install.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Resolves the bundled native LanguageTool server once, at the process edge.
+# Tests and source builds can select an explicit executable through the
+# environment. Released platform gems provide the default under libexec.
+
+require_relative "languagetool"
+
+module SimpleEnglish
+  class Install
+    class SetupError < StandardError
+    end
+
+    attr_reader :executable
+
+    def initialize(executable:)
+      @executable = File.expand_path(executable)
+    end
+
+    def self.from_env(env = ENV)
+      executable = env.fetch(LanguageTool::EXECUTABLE_ENV,
+        LanguageTool::BUNDLED_EXECUTABLE)
+      new(executable: executable)
+    end
+
+    def executable?
+      File.file?(executable) && File.executable?(executable)
+    end
+
+    def executable!
+      return executable if executable?
+      raise SetupError, setup_error
+    end
+
+    def setup_error
+      "lint engine not found or not executable at #{executable}. " \
+        "Install a supported platform build of this gem."
+    end
+  end
+end

data/lib/simple_english/setup/languagetool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Pinned LanguageTool facts shared by the native build and Ruby runtime.
+
+module SimpleEnglish
+  module LanguageTool
+    RULES_FILE = File.expand_path("../../../rules/simple-english.xml", __dir__)
+    LT_VERSION = "6.6"
+    EXECUTABLE_ENV = "SE_LANGUAGETOOL_EXECUTABLE"
+    BUNDLED_EXECUTABLE = File.expand_path(
+      "../../../libexec/simple_english/languagetool-server", __dir__
+    )
+    TIMEOUT_SECONDS = 30
+
+    module_function
+
+    def rule_ids(path = RULES_FILE)
+      File.read(path, encoding: "UTF-8").scan(/<(?:rule|rulegroup)\b[^>]*>/).filter_map do |tag|
+        tag[/\bid="([^"]+)"/, 1]
+      end
+    end
+  end
+end

data/lib/simple_english/version.rb

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

data/lib/simple_english.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# Lint Markdown prose with the SimpleEnglish Plain-mode rules.
+# 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/lint/finding"
+require_relative "simple_english/lint/paragraph"
+require_relative "simple_english/lint/markdown"
+require_relative "simple_english/lint/counts"
+require_relative "simple_english/setup/languagetool"
+require_relative "simple_english/setup/install"
+require_relative "simple_english/lint/extractor"
+require_relative "simple_english/lint/lint_plan"
+require_relative "simple_english/lint/annotated_text"
+require_relative "simple_english/lint/suppressions"
+require_relative "simple_english/setup/config"
+require_relative "simple_english/setup/fingerprint"
+require_relative "simple_english/client/language_tool"
+require_relative "simple_english/client/daemon"
+require_relative "simple_english/daemon/engine"
+require_relative "simple_english/daemon/http"
+require_relative "simple_english/model_context_protocol"
+require_relative "simple_english/daemon/server"
+
+module SimpleEnglish
+  module_function
+
+  # Returns findings, or nil when the daemon is unreachable. The
+  # caller (bin/se) owns the exit status. Diagnostics go to
+  # stderr here.
+  def lint_text(text)
+    return nil unless Client.ensure_up(install: Install.from_env)
+    Client.lint(text)
+  end
+
+  # One entry point for files. LintPlan decides what kind of lint
+  # this is. Both tiers share it, so they cannot drift. Code files
+  # lint comments through the daemon. nil means unreachable:
+  # the caller decides how fatal that is.
+  def lint_file(path, text = File.read(path))
+    language = Extractor.language_for(path)
+    plan = LintPlan.call(text, language)
+    return [] if plan.nil?
+    findings =
+      if plan == :prose
+        lint_text(text)
+      else
+        return nil unless Client.ensure_up(install: Install.from_env)
+        result = Client.lint(text, language: language)
+        if result.nil?
+          warn "error: se daemon did not answer. Run `#{Client.runner} serve` and read its output."
+        end
+        result
+      end
+    return nil unless findings
+    Suppressions.filter(text, findings)
+  end
+end

data/libexec/simple_english/languagetool-server

@@ -0,0 +1,4 @@
+[diffend] Oversized file quarantined before diffing.
+name: data/libexec/simple_english/languagetool-server
+size: 131074312 bytes
+sha256: 34fa51475b10065dfeb151d04c9c2e7bda4a011c8b03b0088110b7285c9ee184