sloplint 0.1.0

data/lib/sloplint/cli.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "json"
+require_relative "version"
+require_relative "rules"
+require_relative "engine"
+require_relative "output"
+
+module Sloplint
+  # Command-line shell: optparse, subcommands, exit codes. See docs/SPEC.md.
+  #
+  # Exit codes: 0 ran/no notes, 1 ran/notes found, 2 bad arguments.
+  module CLI
+    module_function
+
+    def run(argv, out: $stdout, err: $stderr, stdin: $stdin)
+      opts = { format: "full" }
+      parser = global_parser(opts, out:)
+      # Split global options from the subcommand and its args.
+      parser.order!(argv)
+      return 0 if opts[:help_shown] || opts[:version_shown]
+
+      command = argv.shift
+
+      # Bare invocation with piped stdin behaves as `check -`.
+      command ||= (stdin.tty? ? "help" : "check")
+
+      case command
+      when "check"   then cmd_check(argv, opts, out:, err:, stdin:)
+      when "rules"   then cmd_rules(argv, out:)
+      when "explain" then cmd_explain(argv, out:, err:)
+      when "version" then out.puts(VERSION); 0
+      when "help"    then out.puts(parser.help); 0
+      else
+        err.puts("sloplint: unknown command #{command.inspect}")
+        err.puts(parser.help)
+        2
+      end
+    rescue OptionParser::ParseError => e
+      err.puts("sloplint: #{e.message}")
+      2
+    end
+
+    # ── check ───────────────────────────────────────────────────────────────
+    def cmd_check(argv, opts, out:, err:, stdin:)
+      markdown = false
+      select = nil
+      ignore = nil
+      p = OptionParser.new do |o|
+        o.banner = "usage: sloplint check [options] [paths...]  (\"-\" or no paths = stdin)"
+        o.on("-o", "--output-format FORMAT", %w[full json],
+             "Output format: 'full' or 'json' (may also be given before the command).") { |v| opts[:format] = v }
+        o.on("--markdown", "Skip fenced/inline code spans and URLs before scanning.") { markdown = true }
+        o.on("--select IDS", "Only run these rules (comma-separated rule ids or category names).") { |v| select = v.split(",").map(&:strip) }
+        o.on("--ignore IDS", "Skip these rules (comma-separated rule ids or category names).") { |v| ignore = v.split(",").map(&:strip) }
+      end
+      p.order!(argv)
+
+      unknown = unknown_rule_refs(select) + unknown_rule_refs(ignore)
+      unless unknown.empty?
+        err.puts("sloplint: unknown rule or category: #{unknown.join(", ")}")
+        err.puts("run `sloplint rules` to list them.")
+        return 2
+      end
+
+      rules = select_rules(select, ignore)
+      paths = argv.empty? ? ["-"] : argv
+      by_path = paths.reject { |x| x == "-" }.size > 1
+
+      all_notes = []
+      paths.each do |path|
+        text =
+          if path == "-"
+            stdin.read
+          else
+            unless File.file?(path)
+              err.puts("sloplint: no such file: #{path}")
+              return 2
+            end
+            File.read(path)
+          end
+        label = path == "-" ? "-" : path
+        all_notes.concat(Engine.scan(text, rules:, markdown:, path: label))
+      end
+
+      case opts[:format]
+      when "json"
+        out.puts(Output.format_json(all_notes, by_path:))
+      else
+        text = Output.format_human(all_notes)
+        out.puts(text) unless text.empty?
+      end
+
+      all_notes.empty? ? 0 : 1
+    rescue ArgumentError => e
+      err.puts("sloplint: invalid input: #{e.message}")
+      2
+    end
+
+    # ── rules ───────────────────────────────────────────────────────────────
+    def cmd_rules(argv, out:)
+      as_json = false
+      OptionParser.new do |o|
+        o.banner = "usage: sloplint rules [--json]"
+        o.on("--json", "Emit the catalog as JSON for machine enumeration.") { as_json = true }
+      end.order!(argv)
+
+      if as_json
+        payload = RULES.map do |r|
+          { id: r.id, category: r.category, severity: r.severity,
+            message: r.message, suggestion: r.suggestion, default_on: r.default_on }
+        end
+        out.puts(JSON.pretty_generate(payload))
+      else
+        RULES.each do |r|
+          off = r.default_on ? "" : " [off by default]"
+          out.puts("#{r.id.ljust(24)} #{r.category.ljust(14)} #{r.severity.ljust(8)} #{r.message}#{off}")
+        end
+      end
+      0
+    end
+
+    # ── explain ID ────────────────────────────────────────────────────────
+    def cmd_explain(argv, out:, err:)
+      id = argv.shift
+      unless id
+        err.puts("usage: sloplint explain RULE_ID")
+        return 2
+      end
+      rule = RULES.find { |r| r.id == id }
+      unless rule
+        err.puts("sloplint: no such rule: #{id}")
+        err.puts("run `sloplint rules` to list them.")
+        return 2
+      end
+      out.puts(<<~TXT)
+        #{rule.id}  (#{rule.category}, #{rule.severity}#{rule.default_on ? "" : ", off by default"})
+
+        #{rule.message}
+
+        Why: #{rule.rationale}
+        Fix: #{rule.suggestion}
+
+        Flags:    #{rule.examples_bad.join("\n          ")}
+        Does not: #{rule.examples_ok.join("\n          ")}
+      TXT
+      0
+    end
+
+    # ── helpers ─────────────────────────────────────────────────────────────
+    # Ids/categories in refs that match no rule in the catalog. nil (no --select
+    # or --ignore given) passes through as no unknowns.
+    def unknown_rule_refs(refs)
+      return [] unless refs
+
+      known = RULES.flat_map { |r| [r.id, r.category] }.uniq
+      refs - known
+    end
+
+    # --select/--ignore accept rule ids or category names. Default set excludes
+    # default_on:false rules unless they are explicitly selected.
+    def select_rules(select, ignore)
+      rules = if select
+        RULES.select { |r| select.include?(r.id) || select.include?(r.category) }
+      else
+        RULES.select(&:default_on)
+      end
+      if ignore
+        rules = rules.reject { |r| ignore.include?(r.id) || ignore.include?(r.category) }
+      end
+      rules
+    end
+
+    def global_parser(opts, out:)
+      OptionParser.new do |o|
+        o.banner = <<~BANNER
+          sloplint — flag the rhetorical tics and puffery that mark AI-generated prose.
+
+          # Recommended for agents:
+          cat FILE | sloplint check --markdown -o json -
+          # exit 0 = clean, 1 = notes found, >1 = error
+          # each note: {path,line,column,severity,rule,category,message,excerpt,suggestion}
+
+          usage: sloplint [-o full|json] <command> [args]
+
+          commands:
+            check        scan paths (or stdin) for AI-slop tells and report notes [default]
+            rules        list the rule catalog (add --json for the machine-readable form)
+            explain ID   print one rule's message, rationale, and a bad/ok example
+            version      print the sloplint version
+
+          global options:
+        BANNER
+        o.on("-o", "--output-format FORMAT", %w[full json],
+             "Output format: 'full' (human-readable text) or 'json' (default: full).") do |v|
+          opts[:format] = v
+        end
+        o.on("-h", "--help", "Show this help, including the copy-paste agent recipe above.") do
+          out.puts(o.help)
+          opts[:help_shown] = true
+        end
+        o.on("-v", "--version", "Print the sloplint version.") do
+          out.puts(VERSION)
+          opts[:version_shown] = true
+        end
+        o.separator ""
+        o.separator "See `sloplint explain <id>` for any rule, or docs/SPEC.md for the JSON contract."
+      end
+    end
+  end
+end

data/lib/sloplint/engine.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "rules"
+
+module Sloplint
+  # One match = one Note. See docs/SPEC.md "Note".
+  Note = Data.define(
+    :path, :line, :column, :severity, :rule, :category,
+    :message, :excerpt, :count, :suggestion
+  )
+
+  module Engine
+    module_function
+
+    # text: the source. rules: which Rule objects to run. markdown: blank code/URLs first.
+    # path: label carried into each Note (e.g. filename or "-" for stdin).
+    def scan(text, rules: RULES, markdown: false, path: "-")
+      text = blank_markdown(text) if markdown
+      line_starts = line_starts_for(text)
+      notes = []
+      rules.each do |rule|
+        text.to_enum(:scan, rule.pattern).each do
+          m = Regexp.last_match
+          matched = m[0]
+          next if rule.skip.any? { |re| matched.match?(re) }
+
+          count = rule.count_group ? matched.scan(rule.count_group).size : nil
+          line, column = line_col(text, m.begin(0), line_starts:)
+          message = count ? rule.message % { count: count } : rule.message
+          notes << Note.new(
+            path: path, line: line, column: column,
+            severity: rule.severity, rule: rule.id, category: rule.category,
+            message: message, excerpt: matched.gsub(/\s+/, " ").strip,
+            count: count, suggestion: rule.suggestion
+          )
+        end
+      end
+      notes.sort_by { |n| [n.line, n.column] }
+    end
+
+    # 1-indexed line and column for a char offset into text. Binary-searches a
+    # precomputed line_starts table (see line_starts_for) so a scan with many
+    # notes doesn't re-walk the prefix from offset 0 for every single one --
+    # the previous version did text[0, offset] per note, which is O(n) per
+    # call and O(n * notes) overall, quadratic on a large file with many hits.
+    # line_starts is optional so this stays callable standalone.
+    def line_col(text, offset, line_starts: nil)
+      line_starts ||= line_starts_for(text)
+      idx = (line_starts.bsearch_index { |s| s > offset } || line_starts.length) - 1
+      [idx + 1, offset - line_starts[idx] + 1]
+    end
+
+    # Char offset where each line begins, index 0 = line 1. Computed once per
+    # scan and shared across every note instead of recomputed per note.
+    #
+    # Built via each_line + line.length, not repeated String#index(pat, pos)
+    # calls -- on non-ASCII-only text (e.g. curly quotes, em dashes), index
+    # with a start position is not O(1)-amortized per call in CRuby, and a
+    # few thousand newlines turned this quadratic: 7.4s on a 1.2MB UTF-8
+    # file that each_line does in 0.004s.
+    def line_starts_for(text)
+      starts = [0]
+      text.each_line { |line| starts << starts.last + line.length }
+      starts.pop unless text.empty? || text.end_with?("\n")
+      starts
+    end
+
+    # Replace fenced code, inline code, and URLs with same-length whitespace so
+    # line/column stay correct. Newlines are preserved.
+    def blank_markdown(text)
+      blank = lambda { |s| s.gsub(/[^\n]/, " ") }
+      text
+        .gsub(/```.*?```/m) { |s| blank.call(s) }   # fenced code
+        .gsub(/`[^`\n]*`/) { |s| blank.call(s) }    # inline code
+        .gsub(%r{https?://\S+}) { |s| blank.call(s) } # bare URLs
+    end
+  end
+end

data/lib/sloplint/output.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sloplint
+  module Output
+    module_function
+
+    # proselint-style "full" text: one note per line, with excerpt + suggestion.
+    def format_human(notes)
+      return "" if notes.empty?
+
+      notes.map do |n|
+        head = "#{n.path}:#{n.line}:#{n.column}: #{n.severity} #{n.rule}  #{n.message}"
+        excerpt = "    excerpt: #{n.excerpt}"
+        fix = "    fix: #{n.suggestion}"
+        [head, excerpt, fix].join("\n")
+      end.join("\n\n")
+    end
+
+    # JSON: an array of notes, or an object keyed by path when >1 file was scanned.
+    def format_json(notes, by_path: false)
+      if by_path
+        grouped = notes.group_by(&:path).transform_values { |ns| ns.map { |n| note_hash(n) } }
+        JSON.pretty_generate(grouped)
+      else
+        JSON.pretty_generate(notes.map { |n| note_hash(n) })
+      end
+    end
+
+    def note_hash(note)
+      h = note.to_h
+      h.delete(:count) if h[:count].nil?
+      h
+    end
+  end
+end