simple_english 0.6.0-x86_64-linux

data/docs/RULES.md

@@ -0,0 +1,496 @@
+# Rules
+
+Generated by `bin/render-rules`. Do not edit by hand. The source
+of truth is `rules/simple-english.xml` and
+`lib/simple_english/lint/counts.rb`.
+
+## Pattern rules
+
+### SE_NO_CONTRACTIONS: No contractions
+
+Write the words in full. No contractions.
+
+- Wrong: You don't need this file.
+- Right: You do not need this file.
+
+### SE_NO_SEMICOLON: No semicolons
+
+Write two sentences, or name the relation.
+
+- Wrong: Start the tool; then read the log.
+- Right: Start the tool. Then read the log.
+
+### SE_NO_EMDASH: No em-dashes
+
+Write two sentences, or use a comma.
+
+- Wrong: The tool is fast—it also works.
+- Right: The tool is fast. It also works.
+
+### SE_MODAL_RESTRICTED: Only can, will, must
+
+Use can, will, or must. State the requirement exactly.
+
+- Wrong: You should restart the service.
+- Right: You must restart the service.
+
+### SE_ACTIVE_VOICE: Active voice
+
+Use the active voice. Say who does the action.
+
+- Wrong: The log was written by the worker.
+- Right: The worker wrote the log.
+
+### SE_PRESENT_PERFECT: Simple tenses only
+
+Use the simple past. Say when it happened.
+
+- Wrong: The job has completed.
+- Right: The job completed.
+
+### SE_ING_AFTER_COMMA: No -ing after a comma
+
+Start a new sentence instead of the -ing phrase.
+
+- Wrong: The tool runs, making it easy.
+- Right: The tool runs. It is easy.
+
+### SE_KEEP_THAT: make sure that
+
+Write "make sure that".
+
+- Wrong: Make sure the file exists.
+- Right: Make sure that the file exists.
+
+### SE_CONDITION_FIRST: Condition before command
+
+Put the condition first: "If the build fails, read the log."
+
+- Wrong: Read the log if the build fails.
+- Right: If the build fails, read the log.
+
+### SE_SLOP_LEVERAGE: use, not leverage
+
+Write use.
+
+- Wrong: Utilize the registry file.
+- Right: Use the registry file.
+
+### SE_SLOP_IN_ORDER_TO: to, not in order to
+
+Write to.
+
+- Wrong: Run the tool in order to build the file.
+- Right: Run the tool to build the file.
+
+### SE_SLOP_PRIOR_TO: before, not prior to
+
+Write before.
+
+- Wrong: Read the file prior to the upgrade.
+- Right: Read the file before the upgrade.
+
+### SE_SLOP_ENSURE: make sure that, not ensure
+
+Write make sure that.
+
+- Wrong: Ensure the file exists.
+- Right: Make sure that the file exists.
+
+### SE_SLOP_FUNCTIONALITY: function, not functionality
+
+Write function or feature.
+
+- Wrong: Add the functionality first.
+- Right: Add the function first.
+
+### SE_SLOP_ENABLES_YOU: you can, not enables you to
+
+Write you can.
+
+- Wrong: The tool enables you to build the file.
+- Right: You can build the file with the tool.
+
+### SE_SLOP_FACILITATE: help, not facilitate
+
+Write help or make possible.
+
+- Wrong: The tool facilitates the build.
+- Right: The tool helps the build.
+
+### SE_SLOP_DELVE: read, not delve into
+
+Write read or examine.
+
+- Wrong: Delve into the config file.
+- Right: Read the config file.
+
+### SE_SLOP_WHEN_IT_COMES: for, not when it comes to
+
+Write for.
+
+- Wrong: When it comes to builds, use the tool.
+- Right: For builds, use the tool.
+
+### SE_SLOP_IN_THE_EVENT: if, not in the event that
+
+Write if.
+
+- Wrong: In the event that the build fails, read the log.
+- Right: If the build fails, read the log.
+
+### SE_SLOP_DUE_TO_FACT: because, not due to the fact that
+
+Write because.
+
+- Wrong: Due to the fact that the port is closed, the tool fails.
+- Right: Because the port is not open, the tool fails.
+
+### SE_SLOP_AND_OR: no and/or
+
+Pick one. Or write "X, or Y, or both".
+
+- Wrong: Set the flag and/or the port.
+- Right: Set the flag, or the port, or both.
+
+### SE_SLOP_LATIN: no Latin abbreviations
+
+#### e.g.
+
+Write "for example", or name the items.
+
+- Wrong: Set the flag, e.g. the port.
+- Right: Set the flag, for example the port.
+
+#### i.e.
+
+Write "that is", or name the items.
+
+- Wrong: Set the flag, i.e. the port.
+- Right: Set the flag, that is the port.
+
+#### etc.
+
+Name the items.
+
+- Wrong: Set the flag, etc.
+- Right: Set the flag or the port.
+
+### SE_SLOP_OUT_OF_BOX: by default, not out of the box
+
+Write by default.
+
+- Wrong: The tool works out of the box.
+- Right: The tool works by default.
+
+### SE_SLOP_UNDER_HOOD: internally, not under the hood
+
+Write internally.
+
+- Wrong: Under the hood, the tool builds a file.
+- Right: Internally, the tool builds a file.
+
+### SE_SLOP_STREAMLINE: make simpler, not streamline
+
+Write make simpler or make faster.
+
+- Wrong: The tool streamlines the build.
+- Right: The tool makes the build simpler.
+
+### SE_SLOP_PLETHORA: many, not plethora
+
+Write many.
+
+- Wrong: The file has a plethora of rows.
+- Right: The file has many rows.
+
+### SE_SLOP_ADDRESSES: corrects, not addresses the issue
+
+Write corrects the fault or removes the error.
+
+- Wrong: The tool addresses the issue.
+- Right: The tool corrects the fault.
+
+### SE_SLOP_PIVOTAL: important, not pivotal
+
+Write important.
+
+- Wrong: The flag is crucial.
+- Right: The flag is important.
+
+### SE_SLOP_TAPESTRY: no tapestry, testament, synergy
+
+Delete it. State the fact.
+
+- Wrong: The design is a testament to the team.
+- Right: The design shows the work of the team.
+
+### SE_SLOP_INTERPLAY: interaction, not interplay
+
+Write interaction, or delete it.
+
+- Wrong: The interplay of the two tools is complex.
+- Right: The interaction of the two tools is complex.
+
+### SE_SLOP_INTRICATE: complex, not intricate
+
+Write complex.
+
+- Wrong: The config is intricate.
+- Right: The config is complex.
+
+### SE_SLOP_VIBRANT: delete vibrant, nuanced, multifaceted
+
+Delete it, or name the parts.
+
+- Wrong: The tool is nuanced.
+- Right: The tool reads three file types.
+
+### SE_SLOP_REALM: area, not realm or landscape
+
+Write area.
+
+- Wrong: In the realm of builds, use the tool.
+- Right: In the area of builds, use the tool.
+
+### SE_SLOP_GROUNDBREAKING: new, not groundbreaking
+
+Write new, or delete it.
+
+- Wrong: The tool is groundbreaking.
+- Right: The tool is new.
+
+### SE_SLOP_TRANSFORMATIVE: say what changes, not transformative
+
+Delete it. Say what changes.
+
+- Wrong: The tool is transformative.
+- Right: The tool cuts the build time in half.
+
+### SE_SLOP_REVOLUTIONIZE: change, not revolutionize
+
+Write change.
+
+- Wrong: The tool revolutionizes the build.
+- Right: The tool changes the build.
+
+### SE_SLOP_SHOWCASE: show, not showcase
+
+Write show.
+
+- Wrong: The log showcases the error.
+- Right: The log shows the error.
+
+### SE_SLOP_FOSTER: help, not foster
+
+Write help, support, or let.
+
+- Wrong: The tool fosters growth.
+- Right: The tool supports growth.
+
+### SE_SLOP_HARNESS: use, not harness
+
+Write use.
+
+- Wrong: Harness the API.
+- Right: Use the API.
+
+### SE_SLOP_ENHANCE: improve, not enhance
+
+Write improve.
+
+- Wrong: The tool enhances the build.
+- Right: The tool improves the build.
+
+### SE_SLOP_ELEVATE: increase, not elevate
+
+Write increase.
+
+- Wrong: The tool elevates the speed.
+- Right: The tool increases the speed.
+
+### SE_SLOP_FURTHERMORE: also, not furthermore
+
+Write also.
+
+- Wrong: Furthermore, the tool reads the log.
+- Right: The tool also reads the log.
+
+### SE_SLOP_EMBARK: start, not embark
+
+Write start or try.
+
+- Wrong: Embark on the build.
+- Right: Start the build.
+
+### SE_SLOP_METICULOUS: careful, not meticulous
+
+Write careful or carefully.
+
+- Wrong: The tool checks the file meticulously.
+- Right: The tool checks the file carefully.
+
+### SE_SLOP_HOLISTIC: full, not holistic
+
+Write full.
+
+- Wrong: The tool gives a holistic view.
+- Right: The tool gives a full view.
+
+### SE_SLOP_PARADIGM: model, not paradigm
+
+Write model.
+
+- Wrong: The tool changes the paradigm.
+- Right: The tool changes the model.
+
+### SE_SLOP_BOASTS: has, not boasts
+
+Write has.
+
+- Wrong: The tool boasts a log.
+- Right: The tool has a log.
+
+### SE_SLOP_NOTWITHSTANDING: but, not that being said
+
+Write but.
+
+- Wrong: The tool works. That being said, it is slow.
+- Right: The tool works, but it is slow.
+
+### SE_SLOP_NOTWITHSTANDING2: but, not notwithstanding
+
+Write but.
+
+- Wrong: Notwithstanding the log, the tool fails.
+- Right: The log exists, but the tool fails.
+
+### SE_SLOP_DELETE_ADVERBS: delete empty adverbs
+
+Delete it. It carries no fact.
+
+- Wrong: The tool works seamlessly.
+- Right: The tool works.
+
+### SE_SLOP_JUST: delete just
+
+Delete it. It carries no fact.
+
+- Wrong: The tool just works.
+- Right: The tool works.
+
+### SE_SLOP_DELETE_ADJ: delete empty adjectives
+
+Delete it, or give the measurable property.
+
+- Wrong: The tool is robust.
+- Right: The tool retries three times, then stops.
+
+### SE_SLOP_WORTH_NOTING: delete it is worth noting
+
+Delete it. State the fact.
+
+- Wrong: It is worth noting that the tool is slow.
+- Right: The tool is slow.
+
+### SE_SLOP_IMPORTANT_TO: delete it is important to
+
+Delete it. State the fact.
+
+- Wrong: It is important to read the log.
+- Right: Read the log.
+
+### SE_SLOP_DESIGNED_TO: delete is designed to
+
+Say what the tool does.
+
+- Wrong: The tool is designed to read logs.
+- Right: The tool reads logs.
+
+### SE_SLOP_AIMS_TO: delete aims to
+
+Say what the tool does.
+
+- Wrong: The tool aims to read logs.
+- Right: The tool reads logs.
+
+### SE_SLOP_AS_NEEDED: state the condition, not as needed
+
+State the condition.
+
+- Wrong: Restart the tool as needed.
+- Right: Restart the tool every day.
+
+### SE_SLOP_GRACEFULLY: say what it does, not gracefully handles
+
+Say what the tool does: "retries three times, then stops".
+
+- Wrong: The tool gracefully handles the error.
+- Right: The tool retries three times, then stops.
+
+### SE_SLOP_IN_CONCLUSION: delete in conclusion
+
+Delete it. State the fact.
+
+- Wrong: In conclusion, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_IN_SUMMARY: delete in summary
+
+Delete it. State the fact.
+
+- Wrong: In summary, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_AT_END_OF_DAY: delete at the end of the day
+
+Delete it. State the fact.
+
+- Wrong: At the end of the day, the tool works.
+- Right: The tool works.
+
+### SE_SLOP_NESTLED: give the location, not nestled
+
+Give the location.
+
+- Wrong: The file is nestled in the folder.
+- Right: The file sits in the folder.
+
+### SE_SLOP_BUSTLING: busy, not bustling
+
+Write busy.
+
+- Wrong: The bustling market has many files.
+- Right: The busy market has many files.
+
+### SE_SLOP_HOPE_HELPS: delete I hope this helps
+
+Delete it.
+
+- Wrong: I hope this helps. Read the log.
+- Right: Read the log.
+
+### SE_SLOP_DIVE_IN: delete let's dive in
+
+Delete it.
+
+- Wrong: let's dive in. Read the log.
+- Right: Read the log.
+
+## Counting rules
+
+These rules run in Ruby on Markdown text. Code comments do not use
+them. Procedural text is a list item. Descriptive text is every
+other paragraph.
+
+### SE_SENTENCE_TOO_LONG
+
+A sentence with more than 20 words in
+procedural text, or more than 25 words
+in descriptive text.
+
+### SE_PARAGRAPH_TOO_LONG
+
+A paragraph with more than 6
+sentences in descriptive text.
+

data/lib/simple_english/cli.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+# The command-line interface: Thor commands for lint and serve, plus
+# a no-op setup for older callers. bin/se is a thin runner over this,
+# so the installed gem's RubyGems shim can load it.
+
+require "thor"
+require_relative "../simple_english"
+
+module SimpleEnglish
+  class CLI < Thor
+    def self.exit_on_failure? = true
+
+    # Bare file arguments and "-" (stdin) are lint targets, not command
+    # names. Thor only falls back to the default task when the first
+    # argument is an option, so route them to lint explicitly.
+    def self.start(given_args = ARGV, config = {})
+      first = given_args.first
+      if first && !all_commands.key?(first) &&
+          (first == "-" || !first.start_with?("-"))
+        given_args = ["lint", *given_args]
+      end
+      # Thor's own commands (help, tree) return junk like nil or a
+      # Hash, not an exit status. Contract: start always returns an
+      # Integer so every caller (bin/se, tests) can exit on it.
+      status = super
+      status.is_a?(Integer) ? status : 0
+    end
+
+    # The test entry point. It keeps the old module interface.
+    def self.run(argv)
+      start(argv)
+    end
+
+    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],
+      banner: "text|json|sarif"
+    def lint(*paths)
+      if paths.empty?
+        help("lint")
+        return 2
+      end
+      config =
+        begin
+          SimpleEnglish::Config.load
+        rescue SimpleEnglish::Config::ConfigError => e
+          warn "error: #{e.message}"
+          return 2
+        end
+      results = []
+      self.class.expand_paths(paths).each do |path|
+        next if path != "-" && SimpleEnglish::Config.ignore?(config, path)
+        unless path == "-" || File.readable?(path)
+          warn "error: file not readable: #{path}"
+          return 2
+        end
+        text = (path == "-") ? $stdin.read : File.read(path)
+        findings = SimpleEnglish.lint_file(path, text)
+        return 2 if findings.nil? # already warned why
+        SimpleEnglish::Config.filter(config, path, findings).each do |finding|
+          results << [path, finding]
+        end
+      end
+      self.class.report(results, options[:format])
+      results.empty? ? 0 : 1
+    end
+
+    desc "version", "Print the gem version"
+    def version
+      puts SimpleEnglish::VERSION
+      0
+    end
+
+    desc "mcp", "Run the MCP stdio server (one JSON-RPC message per line)"
+    def mcp
+      SimpleEnglish::ModelContextProtocol.run
+      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 `#{Client.runner} 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,
+      SimpleEnglish::Config::ConfigError => e
+      warn "error: #{e.message}"
+      2
+    end
+
+    desc "setup", "Do nothing; the lint engine ships with the gem"
+    def setup
+      puts "nothing to set up; the lint engine ships with the gem"
+      0
+    end
+
+    # "-" stays as-is for stdin. Directories expand to all lintable files.
+    # Glob output keeps a "./" prefix when the argument is ".". Strip it so
+    # paths and config ignore globs always see the same form.
+    # These trees hold third-party prose, not the user's. The tool lints
+    # what the user owns. Skipped only during directory expansion. An
+    # explicit path always lints.
+    # Dir.glob never returns dotfiles, so ".git" is inert today. It
+    # guards a future FNM_DOTMATCH from turning git internals back on.
+    # .gitignore is not read. Users put ignore: globs in the config for
+    # build output and generated files.
+    SKIPPED_DIRS = [".git", "node_modules", "vendor"].freeze
+
+    def self.expand_paths(argv)
+      extensions = (SimpleEnglish::Extractor::EXTENSION_LANGUAGES.keys.map { |e| e.delete_prefix(".") } + ["md"]).uniq.join(",")
+      argv.flat_map do |path|
+        if File.directory?(path)
+          Dir.glob(File.join(path, "**/*.{#{extensions}}"))
+            .reject { |p| p.split(File::SEPARATOR).any? { |s| SKIPPED_DIRS.include?(s) } }
+            .sort
+        else
+          path
+        end
+      end.map { |path| path.delete_prefix("./") }
+    end
+
+    def self.report(results, format)
+      require "json"
+      case format
+      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"
+        puts JSON.pretty_generate(
+          "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}
+              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" => {
+                 "artifactLocation" => {"uri" => path},
+                 "region" => region
+               }}]}
+            end
+          }]
+        )
+      else
+        results.each do |path, finding|
+          puts finding.to_line(path)
+        end
+      end
+    end
+  end
+end