lintus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 981afee300e237f8f7f4435a0ed6e8501caa8d144736eedca394711dfd8c7ad2
+  data.tar.gz: '07488e702c7d8b7f6f43a9bad53add49f5ab723e9b730fbb1514fddf7a860cdf'
+SHA512:
+  metadata.gz: a1660f4d328e3ffba835656b98a8d7d6b856b4f48f5738021d6925ecd79579ab8b50f44a7a675d10dadef66ea3b554ad57afaa2a33e391df2e9de8831f451c7f
+  data.tar.gz: 3c53cb7d2a59175e3fa8a01dfcce390c6fb434700e5439cb76f9067d5472498b11fa1e3416f7f695405d595ee3b03f50eca3811ca822e51fd94c6d911105bb86

data/.pre-commit-hooks.yaml

@@ -0,0 +1,18 @@
+# Hook definition for https://pre-commit.com
+#
+#   repos:
+#     - repo: https://github.com/virolea/lintus
+#       rev: v0.1.0
+#       hooks:
+#         - id: lintus
+#
+# pre-commit passes the staged file names as arguments, so only the files in
+# the commit are sent to the model. JEV_API_KEY must be set in the environment.
+- id: lintus
+  name: lintus
+  description: Lint staged files against the plain-language rules in .lintus.yml, using the Jev model.
+  entry: lintus
+  language: ruby
+  pass_filenames: true
+  require_serial: true
+  additional_dependencies: []

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-09-21
+
+- Initial release.
+- Rules are read from `.lintus.yml` at the repository root and asked to the Jev model as noul questions.
+- Per-rule `paths`, `exclude`, `criteria`, `threshold`, `severity` and `offense_when`.
+- File selection: whole tree, explicit files or directories, `--diff [REF]`, and `--staged`.
+- Output formats: `text`, `github` (workflow annotations) and `json`.
+- `lintus init` writes a starter config; `--list` shows what would be sent without calling the API.
+- A composite GitHub Action (`action.yml`) and a pre-commit hook definition.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Vincent Rolea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,239 @@
+# Lintus
+
+A linter whose rules are written in plain language.
+
+Lintus reads a YAML file of rules at the root of your repository. Each rule is a question
+about a file. For every file a rule applies to, Lintus asks the question to the
+[Jev](https://github.com/virolea/jev) model as a *noul* (a true/false judgement with a
+probability), and reports an offense wherever the answer says so.
+
+```yaml
+# .lintus.yml
+rules:
+  no_sleep_in_jobs:
+    description: Background jobs must never block on sleep.
+    question: Does this file call `sleep` inside a job's perform method?
+    paths:
+      - "app/jobs/**/*.rb"
+```
+
+```
+$ lintus
+app/jobs/retry_job.rb: [no_sleep_in_jobs] Background jobs must never block on sleep. (error, noul 0.94)
+
+42 files inspected, 1 offense detected
+```
+
+It runs on the whole tree, on the files changed since a git ref, or on the files staged for a
+commit, so it fits a CI job as well as a pre-commit hook.
+
+## Installation
+
+```bash
+gem install lintus
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "lintus", group: :development
+```
+
+Lintus needs a Jev API key. Export it as `JEV_API_KEY` or pass `--api-key`.
+
+## Getting started
+
+```bash
+lintus init      # writes a starter .lintus.yml
+lintus --list    # shows which files each rule would be asked about, without calling the API
+lintus           # lints every file
+```
+
+## The config file
+
+Lintus looks for `.lintus.yml` (or `lintus.yml`, `.lintus.yaml`, `lintus.yaml`) in the current
+directory and its parents, the way git finds `.git`. The directory holding the file is the root
+every path is relative to.
+
+```yaml
+# Globs every rule applies to, unless the rule has its own `paths`.
+paths:
+  - "app/**/*.rb"
+  - "lib/**/*.rb"
+
+# Globs no rule ever applies to.
+exclude:
+  - "vendor/**"
+  - "db/schema.rb"
+
+# Files larger than this many bytes are skipped instead of sent to the model. Default 100000.
+max_file_size: 100000
+
+rules:
+  no_raw_sql:
+    description: Build queries with Active Record, not string interpolation.
+    question: Does this file build a SQL string by interpolating or concatenating values into it?
+    criteria:
+      "true": A SQL fragment is assembled from Ruby values with #{}, +, or format.
+      "false": Queries go through Active Record methods or bound parameters, or there is no SQL.
+    threshold: 0.7
+    paths:
+      - "app/**/*.rb"
+    exclude:
+      - "app/models/legacy/**"
+    severity: error
+
+  service_objects_are_documented:
+    description: Service objects carry a comment explaining what they do.
+    question: Does every class in this file have a comment describing its responsibility?
+    offense_when: false
+    severity: warning
+    paths:
+      - "app/services/**/*.rb"
+```
+
+### Rule attributes
+
+| Key            | Required | Meaning |
+| -------------- | -------- | ------- |
+| `question`     | yes      | The noul statement asked of the model. Phrase it so that `true` means the file is an offense. |
+| `description`  | no       | The message printed for an offense. Defaults to the question. |
+| `criteria`     | no       | A map with `"true"` and `"false"` keys spelling out what each answer means. This is how you scope an ambiguous question, and it is worth writing for every rule that matters. |
+| `threshold`    | no       | Probability above which the answer counts as `true`. Defaults to 0.5. Raise it for rules where a false positive is costly. |
+| `paths`        | no       | Globs the rule applies to. Defaults to the top-level `paths`; with neither, every file. |
+| `exclude`      | no       | Globs the rule never applies to, on top of the top-level `exclude`. |
+| `severity`     | no       | `error` (default) or `warning`. Only errors fail the run, unless `--fail-on` says otherwise. |
+| `offense_when` | no       | `true` (default) or `false`. Set to `false` for rules phrased positively, such as "Does every class have a comment?". |
+
+Rule ids are snake_case. They become the question identifiers in the Jev request and the
+`[tag]` in the output.
+
+### Globs
+
+Globs use Ruby's `File.fnmatch` with pathname semantics: `*` does not cross directories,
+`**/` does, and `{a,b}` alternation works. A bare directory (`vendor`) and a trailing `**`
+(`vendor/**`) both match everything beneath it.
+
+### Writing good rules
+
+Every rule that applies to a file is sent in a single request, evaluated in parallel by the
+model. So prefer several narrow questions over one broad one: "Does this file call `sleep`?"
+and "Does this file rescue `Exception`?" as two rules beat "Does this file do anything a job
+should not?".
+
+Lintus sends the model the file's path and its full content. A question can therefore refer to
+the file name ("Is this a controller?") as well as the code.
+
+## Choosing files
+
+| Command                     | Files |
+| --------------------------- | ----- |
+| `lintus`                    | Every file in the tree (tracked and untracked, honouring `.gitignore`). |
+| `lintus app/jobs lib/x.rb`  | The given files and directories. |
+| `lintus --diff`             | Files with uncommitted changes, plus untracked files. |
+| `lintus --diff main`        | Files changed since the merge base with `main`, plus uncommitted and untracked changes. |
+| `lintus --staged`           | Files staged for commit. The staged content is what gets linted, not the working tree. |
+
+Only files that at least one rule applies to are sent. Deleted files are never sent.
+
+## Output
+
+`--format text` is the default. `--format github` prints GitHub Actions workflow commands, so
+each offense becomes an annotation on the file in the pull request; it is the default when
+`GITHUB_ACTIONS` is set. `--format json` is for other tools.
+
+Exit status is `0` when clean, `1` when there are offenses at or above `--fail-on`
+(`error` by default, or `warning`, or `never`), and `2` when a request failed or the
+invocation was wrong.
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/lintus.yml
+name: Lintus
+on: [pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  lintus:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0   # needed to diff against the base branch
+      - uses: virolea/lintus@v0.1.0
+        with:
+          jev-api-key: ${{ secrets.JEV_API_KEY }}
+```
+
+On pull requests the action lints only the files changed against the base branch, and
+annotates them. Set `base: none` to lint everything, or `base: origin/develop` to diff
+against another ref. Extra flags go in `args`. If the workflow already sets up Ruby, the
+action reuses it.
+
+## Pre-commit hook
+
+With [pre-commit](https://pre-commit.com):
+
+```yaml
+repos:
+  - repo: https://github.com/virolea/lintus
+    rev: v0.1.0
+    hooks:
+      - id: lintus
+```
+
+pre-commit passes the staged file names, so only those are checked.
+
+With a plain git hook, use `--staged` so the linted content is what is actually being
+committed:
+
+```bash
+#!/bin/sh
+# .git/hooks/pre-commit
+exec lintus --staged
+```
+
+Either way `JEV_API_KEY` must be in the environment of the shell running the commit.
+
+## Other options
+
+```
+-c, --config PATH      Config file to use instead of searching for one
+-j, --jobs N           Concurrent requests to the Jev API (default 4)
+    --api-key KEY      Jev API key (default: $JEV_API_KEY)
+    --fail-on LEVEL    error (default), warning, or never
+-l, --list             Show what would be checked without calling the API
+```
+
+Rate-limited and overloaded responses are retried with exponential backoff, three times per
+file, before the file is reported as failed.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies, then `bundle exec rake`
+to run the tests and RuboCop. `bin/console` gives you an IRB session with the gem loaded.
+
+The repository lints itself: see `.lintus.yml` and `.github/workflows/lintus.yml`.
+
+### Releasing
+
+Bump `lib/lintus/version.rb`, add the entry to `CHANGELOG.md`, and push a matching tag:
+
+```bash
+git tag v0.1.0 && git push origin v0.1.0
+```
+
+The release workflow checks that the tag matches the version, runs the tests, and pushes the
+gem to rubygems.org through trusted publishing. Alternatively, `bundle exec rake release` does
+the same from a machine that is signed in to rubygems.org.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/virolea/lintus.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/action.yml

@@ -0,0 +1,69 @@
+name: Lintus
+description: Lint a repository against the plain-language rules in its .lintus.yml, using the Jev model.
+author: Vincent Rolea
+branding:
+  icon: check-circle
+  color: purple
+
+inputs:
+  jev-api-key:
+    description: API key for the Typesafe Jev model. Store it as a repository secret.
+    required: true
+  base:
+    description: >-
+      Git ref to diff against; only files changed since it are linted. Defaults to the
+      pull request base branch on pull_request events, and to linting every file otherwise.
+      Pass "none" to always lint every file. Requires `fetch-depth: 0` on actions/checkout.
+    required: false
+    default: ""
+  args:
+    description: Extra arguments for the lintus command, for example "--fail-on warning" or "--jobs 8".
+    required: false
+    default: ""
+  version:
+    description: Version of the lintus gem to install. Defaults to the latest release.
+    required: false
+    default: ""
+  ruby-version:
+    description: Ruby version to set up when the workflow has not done so already.
+    required: false
+    default: "3.3"
+
+runs:
+  using: composite
+  steps:
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ inputs.ruby-version }}
+
+    - name: Install lintus
+      shell: bash
+      env:
+        LINTUS_VERSION: ${{ inputs.version }}
+      run: |
+        if [ -n "$LINTUS_VERSION" ]; then
+          gem install lintus --version "$LINTUS_VERSION"
+        else
+          gem install lintus
+        fi
+
+    - name: Run lintus
+      shell: bash
+      env:
+        JEV_API_KEY: ${{ inputs.jev-api-key }}
+        LINTUS_BASE: ${{ inputs.base }}
+        LINTUS_ARGS: ${{ inputs.args }}
+        PR_BASE_REF: ${{ github.base_ref }}
+      run: |
+        base="$LINTUS_BASE"
+        if [ -z "$base" ] && [ -n "$PR_BASE_REF" ]; then
+          base="origin/$PR_BASE_REF"
+        fi
+
+        if [ -n "$base" ] && [ "$base" != "none" ]; then
+          git fetch --no-tags origin "${base#origin/}" >/dev/null 2>&1 || true
+          lintus --format github --diff "$base" $LINTUS_ARGS
+        else
+          lintus --format github $LINTUS_ARGS
+        fi

data/exe/lintus

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "lintus"
+
+exit Lintus::CLI.new.run(ARGV)

data/lib/lintus/cli.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Lintus
+  # The `lintus` command.
+  class CLI
+    USAGE = <<~USAGE
+      Usage: lintus [options] [FILE...]
+             lintus init
+
+      With no FILE, lints every file in the tree. FILE may be a file or a directory.
+    USAGE
+
+    # `command` is what to do; `selection` is which files, with `ref` for --diff
+    # and `files` for paths given on the command line.
+    Options = Struct.new(
+      :command, :selection, :ref, :files, :config, :format, :jobs, :api_key, :list, :fail_on,
+      keyword_init: true
+    )
+
+    attr_reader :stdout, :stderr
+
+    def initialize(stdout: $stdout, stderr: $stderr, env: ENV, dir: Dir.pwd)
+      @stdout = stdout
+      @stderr = stderr
+      @env = env
+      @dir = dir
+    end
+
+    def run(argv)
+      options = parse(argv)
+
+      case options.command
+      when :exit then 0
+      when :init then init
+      else lint(options)
+      end
+    rescue Error, Jev::Error, OptionParser::ParseError => e
+      stderr.puts "lintus: #{e.message}"
+      2
+    end
+
+    private
+
+    def lint(options)
+      config = Config.load(options.config, dir: @dir)
+      runner = Runner.new(config, jobs: options.jobs)
+      tasks = runner.plan(find_files(config, options))
+      return list(tasks) if options.list
+
+      configure_api_key!(options)
+      report = runner.run(tasks)
+      Formatter.for(options.format).new(stdout).render(report)
+      report.exit_status(fail_on: options.fail_on)
+    end
+
+    def parse(argv)
+      options = default_options
+      positional = build_parser(options).parse(argv)
+      return options if options.command == :exit
+
+      if positional.first == "init"
+        raise OptionParser::InvalidArgument, "init takes no arguments" if positional.size > 1
+
+        options.command = :init
+      elsif positional.any?
+        if options.selection != :all
+          raise OptionParser::InvalidArgument,
+                "FILE arguments cannot be combined with --diff or --staged"
+        end
+
+        options.selection = :explicit
+        options.files = positional
+      end
+      options
+    end
+
+    def default_options
+      Options.new(
+        command: :lint, selection: :all, format: @env["GITHUB_ACTIONS"] == "true" ? "github" : "text",
+        jobs: 4, api_key: @env["JEV_API_KEY"], list: false, fail_on: "error"
+      )
+    end
+
+    def build_parser(options) # rubocop:disable Metrics/MethodLength
+      OptionParser.new do |parser| # rubocop:disable Metrics/BlockLength
+        parser.banner = USAGE
+        parser.separator ""
+        parser.separator "Which files:"
+        parser.on("-d", "--diff [REF]", "Only files changed since REF (default HEAD: uncommitted changes)") do |ref|
+          options.selection = :diff
+          options.ref = ref || "HEAD"
+        end
+        parser.on("-s", "--staged", "Only staged files, reading their staged content (for pre-commit hooks)") do
+          options.selection = :staged
+        end
+        parser.separator ""
+        parser.separator "How to run:"
+        parser.on("-c", "--config PATH",
+                  "Config file (default: nearest #{CONFIG_FILENAMES.first} upwards from the current directory)") do |path|
+          options.config = path
+        end
+        parser.on("-f", "--format FORMAT", Formatter::NAMES,
+                  "Output format: #{Formatter::NAMES.join(", ")} (default: text, or github under GitHub Actions)") do |format|
+          options.format = format
+        end
+        parser.on("-j", "--jobs N", Integer, "Concurrent requests to the Jev API (default 4)") do |jobs|
+          options.jobs = jobs
+        end
+        parser.on("--api-key KEY", "Jev API key (default: $JEV_API_KEY)") { |key| options.api_key = key }
+        parser.on("--fail-on LEVEL", %w[error warning never], "Exit non-zero on: error (default), warning, never") do |level|
+          options.fail_on = level
+        end
+        parser.on("-l", "--list", "List the files and rules that would be checked, without calling the API") do
+          options.list = true
+        end
+        parser.separator ""
+        parser.on("-v", "--version", "Print the version") do
+          stdout.puts "lintus #{VERSION}"
+          options.command = :exit
+        end
+        parser.on("-h", "--help", "Print this help") do
+          stdout.puts parser
+          options.command = :exit
+        end
+      end
+    end
+
+    def find_files(config, options)
+      finder = FileFinder.new(config.root)
+
+      case options.selection
+      when :diff then finder.changed_since(options.ref)
+      when :staged then finder.staged
+      when :explicit then finder.explicit(options.files, from: @dir)
+      else finder.all
+      end
+    end
+
+    def configure_api_key!(options)
+      raise Error, "no API key: set JEV_API_KEY or pass --api-key" if options.api_key.nil? || options.api_key.empty?
+
+      Jev.api_key = options.api_key
+    end
+
+    def list(tasks)
+      tasks.each { |file, rules| stdout.puts "#{file.path}: #{rules.map(&:id).join(", ")}" }
+      stdout.puts "#{tasks.size} file(s) would be checked"
+      0
+    end
+
+    def init
+      path = File.join(@dir, CONFIG_FILENAMES.first)
+      raise Error, "#{path} already exists" if File.exist?(path)
+
+      File.write(path, Template::CONFIG)
+      stdout.puts "Wrote #{path}"
+      0
+    end
+  end
+end

data/lib/lintus/config.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Lintus
+  # The parsed config file. Its directory is the root every path is relative to.
+  class Config
+    DEFAULT_MAX_FILE_SIZE = 100_000
+    KEYS = %w[rules paths exclude max_file_size].freeze
+
+    attr_reader :root, :rules, :paths, :exclude, :max_file_size
+
+    class << self
+      def load(path = nil, dir: Dir.pwd)
+        path ||= locate(dir)
+        unless path
+          raise ConfigError,
+                "No config file found: looked for #{CONFIG_FILENAMES.join(", ")} in #{dir} and its parents"
+        end
+        raise ConfigError, "Config file not found: #{path}" unless File.file?(path)
+
+        path = File.expand_path(path)
+        new(parse(path), root: File.dirname(path))
+      end
+
+      # Walks up from `dir` and returns the first config file found, like git does for .git.
+      def locate(dir)
+        Pathname(dir).expand_path.ascend do |ancestor|
+          CONFIG_FILENAMES.each do |name|
+            candidate = ancestor / name
+            return candidate.to_s if candidate.file?
+          end
+        end
+        nil
+      end
+
+      private
+
+      def parse(path)
+        YAML.safe_load_file(path, permitted_classes: [Symbol], aliases: true) || {}
+      rescue Psych::SyntaxError => e
+        raise ConfigError, "#{path} is not valid YAML: #{e.message}"
+      end
+    end
+
+    def initialize(data, root: Dir.pwd)
+      raise ConfigError, "config must be a map, got #{data.class}" unless data.is_a?(Hash)
+
+      data = data.transform_keys(&:to_s)
+      Schema.reject_unknown_keys!(data, KEYS, context: "config")
+
+      @root = File.expand_path(root)
+      @paths = Schema.string_list(data["paths"])
+      @exclude = Schema.string_list(data["exclude"])
+      @max_file_size = build_max_file_size(data.fetch("max_file_size", DEFAULT_MAX_FILE_SIZE))
+      @rules = build_rules(data["rules"])
+    end
+
+    # The rules that apply to a repository-relative path, in config order.
+    def rules_for(path) = rules.select { |rule| rule.applies_to?(path) }
+
+    def rule(id) = rules.find { |rule| rule.id == id.to_s }
+
+    private
+
+    def build_max_file_size(value)
+      raise ConfigError, "`max_file_size` must be a positive integer of bytes" unless value.is_a?(Integer) && value.positive?
+
+      value
+    end
+
+    def build_rules(rules)
+      raise ConfigError, "`rules` must be a map of rule id => attributes" unless rules.is_a?(Hash)
+      raise ConfigError, "`rules` is empty: nothing to lint" if rules.empty?
+
+      rules.map { |id, attrs| Rule.new(id, attrs, default_paths: paths, default_exclude: exclude) }
+    end
+  end
+end