judgelint 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c59739f54cb0b198f538842c411554b101b4a3a836f641f57e8f1ebd97fca0de
-  data.tar.gz: 42b6bec77cc90b1a2f94b4d8a0782531f21d97ec543ad83df0cebcf67ca83cc9
+  metadata.gz: 204f26e50fb67239d805530c3616f298539f80eddc738f971065996042a6b4cc
+  data.tar.gz: 3c57e02dad382cd5f82ecc6c1936c20ee00b60549e5d9cdfed020f91109c7d05
 SHA512:
-  metadata.gz: ee5af8e99281ac1f1946512a485171f6bf9ad3afdbc4eba3ba251f1694c5315668c0d5185895a057f0f38007c6451dff27f3fedf11635bde51dcace18326e188
-  data.tar.gz: e84ca3de964ffdf65a92f92d6ea095bf0282cc091e4c7b20183a30b50fdab65292e9140511e5e402ffe623962ff4c8b0456a562f06278cc75a8b5c69ea992ed8
+  metadata.gz: c50ecb91cc07c801bc9fa913e2ed9719391b6603fee87fdcb03d2a9e2df6071e3dee5c62e4b74b6e82c7bcf5de9992d9a6174b718bfb9bb3b910e9076fd21a54
+  data.tar.gz: 670f8f274d0409b8682be0a6757f74a8b9bfd3d37b2f6fc02af8399866c4e2eae842c7ebd0c4d23bbe7e3e520f61645f58fae07b6a94fc9be92155a5ec583bc0

data/CHANGELOG.md

@@ -1,24 +1,41 @@
 # Changelog
 
+## 0.1.2 (2026-10-24)
+
+- Each bullet is one choice between breaking the rule, following it, and the
+  rule not applying, in place of two yes/no questions. On the demo app, Jev
+  finds 13 of 14 known violations, up from 12, with half the questions.
+- Findings name the line that breaks the rule, or the file in a directory,
+  when the model is sure of one.
+- Both the System One and OpenAI Decisions protocols send choice questions.
+
+## 0.1.1 (2026-10-23)
+
+- `judgehint:` comments replace `judgelint:disable`. A hint explains why code
+  breaks a rule. judgelint asks each rule whether the hint gives a reason that
+  applies to it, and reports the finding as excused if it does.
+- Each GitHub release has native binaries for macOS and Linux. Install them
+  with Homebrew (`brew install jpcamara/tap/judgelint`) or `install.sh`.
+
 ## 0.1.0 (2026-10-23)
 
-- Specs as praxis reads them: a README (or `*.judgelint.md`) with `paths:`
-  frontmatter, each top-level bullet a rule. The model reads the spec's prose
-  with the file and is asked whether the code breaks each bullet and whether
-  it follows it; optional `violation:` and `compliant:` lines sharpen a
-  bullet. Question rules in `.judgelint/rules/` for conventions a bullet
-  can't carry.
-- Window, file, and directory scopes; `context:` files the model reads but
-  never judges; line ranges on findings.
-- `check`, `test` (examples under `.judgelint/examples/`), `rules`,
-  `providers`, and `init`; `--base` and `--pr` for changes; text, JSON,
-  GitHub annotations, and SARIF.
-- Every request planned and priced before it's sent, with `max_cost_usd`; a
-  cost line on every run; answers cached per model.
-- 16 provider presets over the System One and OpenAI Decisions protocols, and
-  `models:` to average several.
-- Inline `judgelint:disable` comments, with a required reason.
-- No runtime dependencies; platform gems for macOS and Linux carry a native
-  binary built with Spinel.
-- examples/scoop-society: praxis's TypeScript demo, checked against praxis's
-  verdicts.
+- Specs: a README or `*.judgelint.md` with `paths:` in its frontmatter,
+  where each top-level bullet is a rule. The model reads
+  the spec with the file, and each bullet is asked both ways and averaged.
+  `violation:` and `compliant:` lines under a bullet describe it more
+  precisely. Rules that don't fit in a bullet can be written as questions in
+  `.judgelint/rules/`.
+- Rules can apply to every 40 lines, a whole file, or a whole directory.
+  `context:` adds files the model reads but doesn't judge.
+- Commands: `check`, `test`, `rules`, `providers`, and `init`. `--base` and
+  `--pr` check only what changed. Output as text, JSON, GitHub annotations,
+  or SARIF.
+- Requests are planned and priced before any are sent, and `max_cost_usd`
+  stops an expensive run. Every run prints its cost, and answers are cached
+  per model.
+- 16 providers over the System One and OpenAI Decisions APIs. List more than
+  one in `models:` to average their answers.
+- `judgelint:disable` comments, with a required reason.
+- No runtime dependencies. The macOS and Linux gems include a native binary
+  built with Spinel.
+- `examples/scoop-society`, a TypeScript demo app with known violations.

data/README.md

@@ -1,55 +1,66 @@
 # judgelint
 
-Lint for the conventions a linter can't check.
+judgelint checks code against conventions written in plain English. You write
+them as bullets in a README. judgelint asks a decision model, such as
+TypeSafe's Jev, whether each file breaks each bullet, and reports violations
+with line numbers and an exit code like any other linter. Each answer takes a
+few hundred milliseconds and costs a fraction of a cent.
 
-Write your team's conventions as bullets in a README. judgelint asks a System
-One decision model, such as TypeSafe's Jev, whether each file breaks each
-one, and reports violations with line ranges and exit codes, like a linter.
-Answers take a few hundred milliseconds and cost a fraction of a cent.
+## Install
 
-Inspired by [praxis](https://github.com/zarpay/praxis-cli), which reads the
-same kind of specs with chat models. judgelint trades praxis's written
-findings for speed and cost, and reads praxis's specs as they are. Ruby with
-no dependencies; also a native binary, built with
-[Spinel](https://github.com/matz/spinel).
+```sh
+brew install jpcamara/tap/judgelint
+# or
+curl -fsSL https://raw.githubusercontent.com/jpcamara/judgelint/main/install.sh | sh
+```
 
-## Quick start
+The script installs to `~/.local/bin`, or to `$JUDGELINT_INSTALL_DIR`. The
+binaries are on the [releases page](https://github.com/jpcamara/judgelint/releases)
+for macOS and Linux, on arm64 and x86_64. Linux needs glibc 2.35 or newer
+(Ubuntu 22.04, Debian 12). `gem install judgelint` works too, and runs as
+plain Ruby on Windows.
+
+## Getting started
 
 ```sh
-gem install judgelint
-judgelint init                # .judgelint.yml and an example spec
+judgelint init            # writes .judgelint.yml and an example spec
 export TYPESAFE_API_KEY=...
-judgelint test                # judge the spec's examples
-judgelint --base main         # check what changed since main
-judgelint                     # or every file the specs govern
+judgelint test            # checks the example spec against its examples
+judgelint                 # checks every file a spec covers
+judgelint --base main     # checks only what changed since main
 ```
 
-On [praxis's demo](examples/scoop-society) (long messages cut here):
+Here's a run on the [demo app](examples/scoop-society), with the messages shortened:
 
 ```text
 $ judgelint src/services/apply-refund.ts src/features/flavor-of-day
 src/services/apply-refund.ts
-  x error      src/services/domain-failures-are-values-never-exceptions  1-21    0.95  Domain failures are values, never exceptions.
-  x error      src/services/error-messages-are-written-for-the           1-21    0.94  Error messages are written for the API consumer.
-  x error      src/services/every-service-has-a-doc-comment              1-21    0.97  Every service has a doc comment …
+  ? uncertain  src/services/a-service-module-exports-exactly-one         1-21            0.47  A service module exports exactly one entry point.
+  x error      src/services/domain-failures-are-values-never-exceptions  13              1.00  Domain failures are values, never exceptions.
+  x error      src/services/error-messages-are-written-for-the           13              1.00  Error messages are written for the API consumer.
+  ? uncertain  src/services/input-is-validated-before-any-work           10              0.51  Input is validated before any work happens.
+  x error      src/services/every-service-has-a-doc-comment              1-21            1.00  Every service has a doc comment …
 src/features/flavor-of-day
-  x error      src/features/exactly-one-entry-point-index-ts                     0.81  Exactly one entry point, `index.ts`, …
-  x error      src/features/logic-files-are-verb-first-kebab                     0.87  Logic files are verb-first kebab-case …
-  ? uncertain  src/features/no-orphaned-files                                    0.60  No orphaned files.
-  ? uncertain  src/features/the-feature-s-name-describes-the                     0.44  The feature's name describes the capability …
+  x error      src/features/exactly-one-entry-point-index-ts             old-rotation.ts 1.00  Exactly one entry point, `index.ts`, …
+  ? uncertain  src/features/types-live-in-a-dedicated-feature            flavor.ts       0.53  Types live in a dedicated `<feature>-types.ts` file.
+  x error      src/features/logic-files-are-verb-first-kebab             flavor.ts       0.99  Logic files are verb-first kebab-case …
+  x error      src/features/no-orphaned-files                            old-rotation.ts 0.79  No orphaned files.
 
-2 files, 5 violations, 2 uncertain
-judgelint: 2 requests, 3,320 input tokens, $0.0001
+2 files, 6 violations, 3 uncertain
+judgelint: 2 requests, 6,437 input tokens, $0.0003
 ```
 
-Exit status: 0 clean, 1 violations (or misjudged examples for `judgelint
-test`), 2 for usage, configuration, or model errors. Everything that can be
-checked is checked before the first paid request.
+A finding names the line that breaks the rule, or the file in a directory,
+when the model is sure of one. Otherwise it shows the lines it was asked
+about.
+
+It exits 1 when there are violations, and 2 on a usage, config, or model
+error. Config problems are caught before any request is sent.
 
-## Specs
+## Writing specs
 
-A README, or any `*.judgelint.md`, whose frontmatter has `paths:` is a spec.
-Each top-level bullet is a rule.
+A spec is a README, or any file ending in `.judgelint.md`, with `paths:` in
+its frontmatter. Each top-level bullet is a rule.
 
 ```markdown
 ---
@@ -63,16 +74,13 @@ excludes: ["src/services/legacy-import.ts"]
 - **No I/O except through the injected Store.** No timers, no fetch, no console.
 ```
 
-The model reads the spec's prose and the whole file, with numbered lines, and
-is asked each bullet two ways: "Do lines 1-40 of the file clearly violate the
-following team rule?" and "Do they follow it, or does it not apply?" The two
-answers lean opposite ways, so their average is steadier than either. Rules
-are named from their lead words (`src/services/no-i-o-except-through-the`),
-and a bullet that says "should" or "prefer" is a warning, anything else an
-error.
+The model gets the spec and the numbered file. For each bullet, it chooses
+whether the code breaks it, follows it, or isn't covered by it, and which line
+breaks it most clearly. A rule's id comes from the start of its bullet, like
+`src/services/no-i-o-except-through-the`. Bullets that say "should" or
+"prefer" are warnings, and the rest are errors.
 
-To sharpen a bullet, say what breaking and following it look like, on
-indented lines under it:
+If the model misreads a bullet, describe breaking and following it:
 
 ```markdown
 - **No I/O except through the injected Store.** No timers, no fetch, no console.
@@ -80,22 +88,24 @@ indented lines under it:
   compliant: reads and writes only through the Store it's given
 ```
 
-They make the model more decisive, and like any wording, they're worth
-checking against examples.
+They make the model more decisive. A loose description can also flag code
+you meant to allow, so check them against examples.
 
-| Frontmatter | |
+| Frontmatter | What it does |
 |---|---|
-| `paths`, `excludes` | Globs for the files the spec governs, from the project root. |
-| `context` | Files the model reads alongside, such as shared types, but never judges. |
-| `scope` | `window` (default) asks about each 40 lines, so findings name lines; `file` asks once per file; `directory` asks once per directory `paths` matches, with every file in it. Praxis's `cohort: by_file` and `by_directory` work too. |
-| `severity`, `threshold` | Override the wording's severity, or the config's threshold, for every rule in the spec. |
+| `paths`, `excludes` | Globs for the files the spec covers, relative to the project root. |
+| `context` | Files the model reads along with each file, like shared types. They're never judged. |
+| `scope` | `window`, the default, asks about every 40 lines so findings have line numbers. `file` asks once per file. `directory` asks once per directory, shows the model every file in it, and names the file that breaks the rule. |
+| `severity`, `threshold` | Set the severity or threshold for every rule in the spec. |
 
-A rule's answer is the probability the code breaks it: at or above the
-threshold (0.7) it's a violation, within 0.3 below it's uncertain (reported,
-never failing).
+Each answer is the probability that the code breaks the rule. At 0.7 or above
+it's a violation. Between 0.4 and 0.7 it's reported as uncertain, which
+doesn't fail the run.
 
-**When a bullet isn't enough**, write that rule as a question in
-`.judgelint/rules/<id>.md`, with criteria the model weighs its answer against:
+### Rules written as questions
+
+When a convention doesn't fit in a bullet, write it as a question in
+`.judgelint/rules/<id>.md`:
 
 ```markdown
 ---
@@ -108,19 +118,29 @@ paths: ["src/features/*"]
 Every file in a feature is reachable from index.ts.
 ```
 
-`fail_when: no` inverts a question like "Does this service validate its
-input first?".
+Add `fail_when: no` when a "no" is the violation, as in "Does this service
+validate its input first?"
+
+## Explaining exceptions
+
+When code breaks a rule on purpose, explain why in a `judgehint:` comment. Any
+comment style works.
+
+```ts
+// judgehint: throwing is intentional. Only the nightly job calls this, after
+// checking the review, so a bad id here is a programmer error.
+```
 
-**Suppress** a finding where a person has decided the code is fine, with a
-reason: `# judgelint:disable <rule> -- <reason>` covers the 40 lines it's in,
-and `judgelint:disable-file` the whole file. Any comment style works.
+For each rule, judgelint asks whether a hint in the same 40 lines gives a
+reason the code can break it. If it does, the finding is reported as excused
+and doesn't fail the run. A hint only excuses the rule it explains, and a hint
+with no reason, like "this is intentional", doesn't excuse anything.
 
-## Examples
+## Testing rules
 
-Decision models classify well and apply policies less well, so the way to
-know a rule works is to try it. Put examples under
-`.judgelint/examples/<rule id>/pass/` (must not be violations) and `fail/`
-(must be), and `judgelint test` reports what the model gets wrong:
+Test each rule against examples. Put files that follow it in
+`.judgelint/examples/<rule id>/pass/` and files that break it in `fail/`.
+`judgelint test` shows which ones the model gets wrong:
 
 ```text
 lib/no-silent-rescues  9/10
@@ -129,61 +149,52 @@ lib/no-silent-rescues  9/10
   ok   fail 0.94  .judgelint/examples/lib/no-silent-rescues/fail/assigns_default.rb
 ```
 
-A miss means the bullet needs rewording or the convention is too broad for
-one question. (Saying a retry that eventually raises is fine took this repo's
-own rule, in [lib/README.md](lib/README.md), to 10/10.) The model sees each
-example's path relative to `pass/` or `fail/`, so the directory never gives
-the answer away. For a directory rule, each example is a directory.
+When an example fails, reword the bullet or split it into narrower rules. The
+model doesn't see the `pass/` or `fail/` part of the path. For a directory
+rule, each example is a directory.
 
-## In CI
+## CI
 
 ```sh
-judgelint --base main            # since the merge base with main, uncommitted work included
-judgelint --pr                   # the pull request's base branch
-judgelint --pr --format github   # annotations on the changed lines (also: json, sarif)
+judgelint --base main            # changes since the merge base with main, plus uncommitted work
+judgelint --pr                   # changes in the current pull request
+judgelint --pr --format github   # GitHub annotations on the changed lines (json and sarif work too)
 ```
 
-`--base` asks only about the 40-line windows a change touched, and about
-directories with a changed file, so old code can't block new work. `--pr`
-reads the base branch from the CI (GitHub Actions, GitLab, Buildkite,
-Bitbucket, Azure Pipelines, or `JUDGELINT_BASE_BRANCH`), then `gh`. Check out
-enough history for the merge base.
+These only ask about the 40-line windows that changed, so existing code
+doesn't block a new pull request. `--pr` gets the base branch from GitHub
+Actions, GitLab, Buildkite, Bitbucket, Azure Pipelines,
+`JUDGELINT_BASE_BRANCH`, or `gh`. Fetch enough history for git to find the
+merge base.
 
 ## Configuration
 
 `.judgelint.yml` has four settings:
 
 ```yaml
-models: [typesafe]       # a model is provider[:model]; list two to average their answers
+models: [typesafe]       # provider or provider:model; list two to average them
 threshold: 0.7
-ignore: ["vendor/**"]    # files no rule judges, and READMEs that are never specs
-max_cost_usd: 1.00       # refuse a run estimated over this, unless --yes
+ignore: ["vendor/**"]    # files no rule checks, and READMEs that aren't specs
+max_cost_usd: 1.00       # refuse a run estimated to cost more, unless --yes
 ```
 
-Flags: `--base`, `--pr`, `--format`, `--model` (replaces `models` for one
-run), `--no-cache`, `--yes`, `--config`.
-
-Every run ends with its cost. Answers are cached in `.judgelint/cache.json`
-by file, question, and model, so an unchanged file costs nothing; commit the
-cache to share it.
+Every run prints what it cost. Answers are cached in `.judgelint/cache.json`,
+so a file that hasn't changed costs nothing. Commit the cache to share it.
+`judgelint --help` lists the flags.
 
-**Two models are more certain than one.** On praxis's demo, Jev alone leaves
-9 to 11 findings uncertain; averaging Jev and Cloudflare's Clef leaves 4, with
-the same 12 of 14 violations found and none false, for $0.02 a run
-(`models: [typesafe, cloudflare]`). Each model's answers are cached on their
-own, and all of a file's requests go out at once. The
-[example](examples/scoop-society) compares the models one at a time.
+List two models to average their answers, like `models: [typesafe,
+cloudflare]`. Each model's answers are cached separately.
 
 ### Providers
 
-`judgelint providers` lists them. Live-tested: `typesafe` (Jev, the default),
-`openrouter`, `celeris`, `cloudflare`, and `openai` (its Decisions API). From
-their docs: `perplexity`, `vercel`, `digitalocean`, `upstage`, `hanzo`,
-`foundry`, `databricks`, and local `ollama`, `llamacpp`, `vllm`, and
-`litellm`. Each reads its key from the usual variable (`TYPESAFE_API_KEY`,
-`CLOUDFLARE_API_TOKEN`, and so on).
+`judgelint providers` lists them. Tested against the live APIs: `typesafe`
+(Jev, the default), `openrouter`, `celeris`, `cloudflare`, and `openai`.
+Set up from their docs: `perplexity`, `vercel`, `digitalocean`, `upstage`,
+`hanzo`, `foundry`, `databricks`, `ollama`, `llamacpp`, `vllm`, and
+`litellm`. Each one reads its key from the provider's usual variable, like
+`TYPESAFE_API_KEY`.
 
-Any other System One or Decisions endpoint is a mapping in `models`:
+For any other System One or Decisions endpoint, add a mapping to `models`:
 
 ```yaml
 models:
@@ -194,32 +205,26 @@ models:
     # headers: {}   provider_options: {}   price_per_million: 0.04   batch_size: 32
 ```
 
-## Native binary
-
-```sh
-git clone https://github.com/matz/spinel && (cd spinel && make deps && make)
-SPINEL=../spinel/bin/spinel rake spinel        # build/judgelint
-SPINEL=../spinel/bin/spinel rake test:spinel   # the tests, against it too
-```
+## Building from source
 
-On macOS and Linux, `gem install` picks a platform gem with the binary
-inside, statically linked, and links the `judgelint` command straight to it;
-elsewhere, Windows included, the gem runs as plain Ruby. The binary starts in
-4 ms against CRuby's 110, and in a 300-file benchmark it was 1.4x faster than
-CRuby on one thread and 2x on eight. Under Bundler, `bundle exec` spends about
-100 ms loading Bundler first; to skip it, link the binary
-(`ln -s "$(bundle info judgelint --path)/libexec/judgelint" bin/judgelint`). The code stays inside what Spinel
-compiles: plain classes instead of `Data.define`, a hand-written option
-parser, no gems.
-
-## Development
+judgelint is written in Ruby and compiled with
+[Spinel](https://github.com/matz/spinel).
 
 ```sh
 bundle install
 bundle exec rake test
-bundle exec rake example      # re-ask Jev about praxis's demo and check it
+git clone https://github.com/matz/spinel ../spinel && (cd ../spinel && make deps && make)
+SPINEL=../spinel/bin/spinel bundle exec rake spinel        # builds build/judgelint
+SPINEL=../spinel/bin/spinel bundle exec rake test:spinel   # runs the tests against the binary
+bundle exec rake example                                   # asks Jev about the demo app again
 ```
 
+## Credits
+
+judgelint was inspired by [praxis](https://github.com/zarpay/praxis-cli), and
+it reads praxis specs, including `cohort: by_file` and `by_directory`. The
+demo app in [examples/scoop-society](examples/scoop-society) comes from praxis.
+
 ## License
 
-MIT
+MIT. The demo app keeps praxis's MIT license.

data/lib/judgelint/cli.rb

@@ -10,8 +10,8 @@ module Judgelint
     HELP = <<~TEXT
       Usage: judgelint [command] [options] [paths...]
 
-      Checks files against conventions written as bullets in READMEs, by asking a
-      System One decision model (Jev by default) whether the code breaks each one.
+      Checks code against the conventions in your specs. For each file and each
+      rule, it asks a decision model (Jev by default) whether the code breaks it.
 
       Commands:
         check [paths...]   Check the files the specs govern, or these (default).

data/lib/judgelint/protocol.rb

@@ -1,11 +1,13 @@
 # frozen_string_literal: true
 
 module Judgelint
-  # The two request shapes decision models are served with. judgelint asks only
-  # yes/no questions, so each renders a Question as that protocol's yes/no
-  # type and reads back the probability of yes. A nil probability is a refusal.
+  # The two request shapes decision models are served with. Each renders a
+  # Question as a yes/no question or a choice, and reads back the probability
+  # of yes, or a choice's probabilities as {option => probability}. A nil
+  # answer is a refusal.
   module Protocol
-    # TypeSafe's System One: questions keyed by name, yes/no is "noul".
+    # TypeSafe's System One: questions keyed by name, yes/no is "noul", and a
+    # choice's options are its criteria.
     module SystemOne
       def self.payload(model, state, questions)
         rendered = {}
@@ -16,6 +18,8 @@ module Judgelint
       end
 
       def self.render(question)
+        return { "type" => "choice", "instructions" => question.instructions, "criteria" => question.options } if question.choice?
+
         rendered = { "type" => "noul", "instructions" => question.instructions }
         criteria = {}
         criteria["true"] = question.yes_means if question.yes_means
@@ -30,14 +34,18 @@ module Judgelint
 
         probabilities = {}
         questions.each do |question|
-          probabilities[question.key] = Protocol.probability(answers[question.key], "noul", question)
+          answer = answers[question.key]
+          probabilities[question.key] =
+            question.choice? ? Protocol.distribution(answer, answer.is_a?(Hash) ? answer["probabilities"] : nil, question)
+                             : Protocol.probability(answer, "noul", question)
         end
         probabilities
       end
     end
 
     # OpenAI's Decisions API: questions are a list with names, yes/no is
-    # "predicate" with no criteria field, and answers come back as a list.
+    # "predicate" with no criteria field, a choice lists its options as
+    # {value, description}, and answers come back as a list.
     module Decisions
       # Decisions' input is text, so a structured state goes as its JSON.
       def self.payload(model, state, questions)
@@ -45,8 +53,16 @@ module Judgelint
         { "model" => model, "input" => input, "questions" => questions.map { |question| render(question) } }
       end
 
-      # Criteria become lines of the instructions, as RubyLLM and LiteLLM do.
+      # A yes/no question's criteria become lines of its instructions, as
+      # RubyLLM and LiteLLM do.
       def self.render(question)
+        if question.choice?
+          choices = question.options.map do |value, description|
+            description ? { "value" => value, "description" => description } : { "value" => value }
+          end
+          return { "type" => "choice", "name" => question.key, "instructions" => question.instructions, "choices" => choices }
+        end
+
         lines = [question.instructions]
         lines << "Yes: #{question.yes_means}" if question.yes_means
         lines << "No: #{question.no_means}" if question.no_means
@@ -68,10 +84,19 @@ module Judgelint
         probabilities = {}
         questions.each do |question|
           answer = by_name.key?(question.key) ? by_name[question.key] : unnamed.shift
-          probabilities[question.key] = Protocol.probability(answer, "probability", question)
+          probabilities[question.key] =
+            question.choice? ? Protocol.distribution(answer, listed(answer), question) : Protocol.probability(answer, "probability", question)
         end
         probabilities
       end
+
+      # [{value, probability}] as {value => probability}.
+      def self.listed(answer)
+        list = answer.is_a?(Hash) ? answer["probabilities"] : nil
+        return nil unless list.is_a?(Array)
+
+        list.to_h { |entry| [entry["value"].to_s, entry["probability"]] }
+      end
     end
 
     ALL = { "system_one" => SystemOne, "decisions" => Decisions }.freeze
@@ -84,5 +109,14 @@ module Judgelint
 
       value.to_f
     end
+
+    def self.distribution(answer, probabilities, question)
+      return nil if answer.is_a?(Hash) && answer["type"] == "refusal"
+      raise ApiError, "No choice answer for #{question.key}: #{answer.inspect}" unless probabilities.is_a?(Hash)
+
+      found = {}
+      question.options.each_key { |option| found[option] = probabilities[option].to_f }
+      found
+    end
   end
 end

data/lib/judgelint/question.rb

@@ -4,39 +4,75 @@ module Judgelint
   # One rule asked about one range of a file. The model sees the whole file;
   # the question points at the lines.
   #
-  # A spec's bullet is asked twice: whether the code breaks it, and, with the
-  # answer flipped, whether the code follows it. Decision models lean toward
-  # no on the first and yes on the second, so the average is steadier than
-  # either.
+  # A spec's bullet is a choice between breaking the rule, following it, and
+  # the rule not applying. With the three side by side, a decision model
+  # commits to an answer, where a yes/no question gets a hedge. The same
+  # request asks which line (or, for a directory, which file) breaks the rule
+  # most clearly, so a finding can name it.
+  #
+  # A rule written as a question is asked yes or no, as written. Code with a
+  # judgehint comment is also asked, yes or no, whether the hint excuses it.
   class Question
     BREAKS = "The code clearly breaks the rule."
-    FOLLOWS = "The code follows the rule, or the rule doesn't apply to it."
+    FOLLOWS = "The code follows the rule."
+    NOT_APPLICABLE = "The rule doesn't apply to this code."
+    EXCUSED = "A judgehint comment is about this rule, and gives a reason the code may break it."
+    NOT_EXCUSED = "No judgehint comment is about this rule. Any judgehint is about a different rule, or gives no reason."
 
-    attr_reader :rule, :first, :last
+    attr_reader :rule, :first, :last, :places
 
-    def initialize(rule, first, last, inverted: false)
+    # +kind+ is :verdict, :where, or :excuse. +places+ are a :where question's
+    # options: line ids (L12) or the directory's files, as the model sees them.
+    def initialize(rule, first, last, kind: :verdict, places: [])
       @rule = rule
       @first = first
       @last = last
-      @inverted = inverted
+      @kind = kind
+      @places = places
+    end
+
+    def excuse?
+      @kind == :excuse
+    end
+
+    def where?
+      @kind == :where
+    end
+
+    # A spec's bullet and its location are choices; everything else is yes or no.
+    def choice?
+      where? || (@kind == :verdict && !rule.convention.nil?)
     end
 
     def key
       base = "#{rule.question_key}.#{first}-#{last}"
-      return base unless rule.convention
+      return "#{base}.excused" if excuse?
+      return "#{base}.where" if where?
+
+      base
+    end
+
+    # A choice's options, as {name => description or nil}.
+    def options
+      return places.to_h { |place| [place, nil] } if where?
 
-      @inverted ? "#{base}.follows" : "#{base}.breaks"
+      { "breaks" => rule.yes_means || BREAKS, "follows" => rule.no_means || FOLLOWS, "not_applicable" => NOT_APPLICABLE }
     end
 
-    # The probability the code breaks the rule, from the probability of yes.
-    def violation(yes_probability)
-      @inverted ? 1.0 - yes_probability : rule.violation_probability(yes_probability)
+    # The probability the code breaks the rule, from a verdict's answer: a
+    # choice's probabilities, or a yes/no question's probability of yes.
+    def violation(answer)
+      return answer["breaks"].to_f if answer.is_a?(Hash)
+
+      rule.violation_probability(answer)
     end
 
     # "Answer yes only when..." keeps the model from flagging code the rule
     # doesn't cover.
     def instructions
-      return convention_instructions if rule.convention
+      return excuse_instructions if excuse?
+      return where_instructions if where?
+      return "How #{rule.scope == 'file' ? 'does' : 'do'} #{subject} relate to the following team rule? Rule: #{rule.convention}" if rule.convention
 
       text = rule.window? ? "Look at lines #{first}-#{last} of the file; the rest is context. #{rule.question}" : rule.question
       return text unless rule.fail_when == "yes"
@@ -47,54 +83,41 @@ module Judgelint
     end
 
     def yes_means
-      return rule.yes_means unless rule.convention
+      return EXCUSED if excuse?
+      return nil if choice?
 
-      @inverted ? rule.no_means || FOLLOWS : rule.yes_means || BREAKS
+      rule.yes_means
     end
 
     def no_means
-      return rule.no_means unless rule.convention
+      return NOT_EXCUSED if excuse?
+      return nil if choice?
 
-      @inverted ? rule.yes_means || BREAKS : rule.no_means || FOLLOWS
+      rule.no_means
     end
 
     def digest
-      @digest ||= Digest::SHA256.hexdigest(JSON.generate([instructions, yes_means.to_s, no_means.to_s]))
+      @digest ||= Digest::SHA256.hexdigest(JSON.generate([instructions, yes_means.to_s, no_means.to_s,
+                                                          choice? ? options.to_a : []]))
     end
 
     private
 
-    # The spec's prose is in the state as team_rules, so the bullet is "the
-    # following team rule".
-    def convention_instructions
-      ask =
-        case rule.scope
-        when "window"
-          if @inverted
-            "Do lines #{first}-#{last} of the file follow the following team rule, or does it not apply to them? " \
-              "Answer false only when those lines clearly break it."
-          else
-            "Do lines #{first}-#{last} of the file clearly violate the following team rule? Answer true only " \
-              "when the code breaks the rule, not when the rule does not apply to it."
-          end
-        when "file"
-          if @inverted
-            "Does the file follow the following team rule, or does it not apply to it? Answer false only when " \
-              "the file clearly breaks it."
-          else
-            "Does the file clearly violate the following team rule? Answer true only when the code breaks the " \
-              "rule, not when the rule does not apply to it."
-          end
-        else
-          if @inverted
-            "Do the files follow the following team rule, or does it not apply to them? Answer false only when " \
-              "they clearly break it."
-          else
-            "Do the files clearly violate the following team rule? Answer true only when the code breaks the " \
-              "rule, not when the rule does not apply to it."
-          end
-        end
-      "#{ask} Rule: #{rule.convention}"
+    def subject
+      { "window" => "lines #{first}-#{last} of the file", "file" => "the file", "directory" => "the files" }
+        .fetch(rule.scope)
+    end
+
+    def where_instructions
+      which = rule.directory? ? "Which file" : "Which line, given by its number as L<number>,"
+      "#{which} most clearly breaks the following team rule? Rule: #{rule.convention}"
+    end
+
+    def excuse_instructions
+      where = { "window" => "in lines #{first}-#{last} of the file", "file" => "in the file", "directory" => "in the files" }
+              .fetch(rule.scope)
+      "Does a judgehint comment #{where} explain why the code intentionally departs from the following team " \
+        "rule, with a reason specific to this rule? Rule: #{rule.convention || rule.message}"
     end
   end
 end

data/lib/judgelint/reporter.rb

@@ -5,8 +5,8 @@ module Judgelint
   # goes to stdout; anything else goes to stderr.
   class Reporter
     FORMATS = %w[text json github sarif].freeze
-    MARKS = { violation: "x", uncertain: "?", skipped: "-", refused: "-", suppressed: "-" }.freeze
-    STATUSES = %w[violation uncertain pass skipped refused suppressed].freeze
+    MARKS = { violation: "x", uncertain: "?", skipped: "-", refused: "-", excused: "-" }.freeze
+    STATUSES = %w[violation uncertain pass skipped refused excused].freeze
 
     def initialize(out, format:)
       @out = out
@@ -46,21 +46,27 @@ module Judgelint
     def text(verdicts, file_count)
       shown = verdicts.reject { |verdict| verdict.status == :pass }
       width = shown.map { |verdict| verdict.rule.id.size }.max
+      places = [7, *shown.map { |verdict| range(verdict).size }].max
       shown.group_by(&:path).each do |path, group|
         @out.puts path
-        group.each { |verdict| @out.puts "  #{line(verdict, width)}" }
+        group.each { |verdict| @out.puts "  #{line(verdict, width, places)}" }
       end
       @out.puts "" unless shown.empty?
       @out.puts summary(verdicts, file_count)
     end
 
-    def line(verdict, width)
+    def line(verdict, width, places)
       label = verdict.status == :violation ? verdict.rule.severity : verdict.status.to_s
-      format("%s %-10s %-#{width}s  %-7s %s  %s", MARKS.fetch(verdict.status), label, verdict.rule.id,
+      format("%s %-10s %-#{width}s  %-#{places}s %s  %s", MARKS.fetch(verdict.status), label, verdict.rule.id,
              range(verdict), probability(verdict), verdict.rule.message)
     end
 
+    # The line that breaks the rule, or the range asked about; for a
+    # directory, the file in it.
     def range(verdict)
+      return verdict.file.delete_prefix("#{verdict.path}/") if verdict.file
+      return verdict.line.to_s if verdict.line
+
       verdict.lines ? verdict.lines.join("-") : ""
     end
 
@@ -76,7 +82,7 @@ module Judgelint
       parts << "#{counts[:uncertain]} uncertain" if counts[:uncertain]
       parts << "#{counts[:skipped]} skipped (too large)" if counts[:skipped]
       parts << "#{counts[:refused]} refused by the model" if counts[:refused]
-      parts << "#{counts[:suppressed]} suppressed" if counts[:suppressed]
+      parts << "#{counts[:excused]} excused by judgehints" if counts[:excused]
       parts.join(", ")
     end
 
@@ -107,8 +113,12 @@ module Judgelint
       level = { violation: verdict.rule.error? ? "error" : "warning", uncertain: "notice" }[verdict.status]
       return unless level
 
-      properties = ["file=#{escape(verdict.path, true)}"]
-      properties += ["line=#{verdict.lines[0]}", "endLine=#{verdict.lines[1]}"] if verdict.lines
+      properties = ["file=#{escape(verdict.file || verdict.path, true)}"]
+      if verdict.line
+        properties << "line=#{verdict.line}"
+      elsif verdict.lines
+        properties += ["line=#{verdict.lines[0]}", "endLine=#{verdict.lines[1]}"]
+      end
       properties << "title=#{escape("judgelint #{verdict.rule.id}", true)}"
       @out.puts "::#{level} #{properties.join(',')}::#{escape("#{verdict.rule.message} (#{probability(verdict)})", false)}"
     end
@@ -135,12 +145,16 @@ module Judgelint
     end
 
     def sarif_result(verdict)
-      region = verdict.lines ? { "startLine" => verdict.lines[0], "endLine" => verdict.lines[1] } : {}
+      region =
+        if verdict.line then { "startLine" => verdict.line }
+        elsif verdict.lines then { "startLine" => verdict.lines[0], "endLine" => verdict.lines[1] }
+        else {}
+        end
       level = verdict.status == :uncertain ? "note" : (verdict.rule.error? ? "error" : "warning")
       {
         "ruleId" => verdict.rule.id, "level" => level,
         "message" => { "text" => "#{verdict.rule.message} (#{probability(verdict)})" },
-        "locations" => [{ "physicalLocation" => { "artifactLocation" => { "uri" => verdict.path }, "region" => region } }]
+        "locations" => [{ "physicalLocation" => { "artifactLocation" => { "uri" => verdict.file || verdict.path }, "region" => region } }]
       }
     end
   end

data/lib/judgelint/runner.rb

@@ -14,18 +14,17 @@ module Judgelint
     # One file's work: the questions to ask, each model's answers (from the
     # cache or the model), and the requests still to send.
     class Job
-      attr_reader :source, :state, :state_digest, :questions, :suppressed, :answers, :requests, :expected
+      attr_reader :source, :state, :state_digest, :questions, :answers, :requests, :expected
       attr_accessor :skipped
 
       # The state is built and hashed once: it's the whole file, and every
       # question's cache key needs its hash. Rules from a spec read its prose
       # alongside the file, as team_rules.
-      def initialize(source, questions, suppressed, prose: nil, expected: nil)
+      def initialize(source, questions, prose: nil, expected: nil)
         @source = source
         @state = prose ? { "team_rules" => prose, "file" => source.state } : source.state
         @state_digest = Digest::SHA256.hexdigest(JSON.generate(@state))
         @questions = questions
-        @suppressed = suppressed
         @answers = {} # model index => {question key => probability or nil}
         @requests = []
         @expected = expected
@@ -44,6 +43,25 @@ module Judgelint
       end
     end
 
+    # One range's averaged answers: the probability it breaks the rule, and
+    # where, when the model is sure enough of one line or file.
+    class Window
+      attr_reader :first, :last, :probability, :place
+
+      def initialize(first, last, probability, place)
+        @first = first
+        @last = last
+        @probability = probability
+        @place = place
+      end
+    end
+
+    # A finding names a line or file when it gets at least this share of the
+    # "where" answer.
+    PLACE_AT = 0.5
+    # A choice takes at most this many options.
+    MAX_OPTIONS = 255
+
     # +clients+ has one Client per model in config.models.
     def initialize(config:, rules:, clients:, cache:)
       @config = config
@@ -143,32 +161,35 @@ module Judgelint
     end
 
     def plan_file(source, rules, lines, expected: nil)
-      unknown = source.suppressed_ids - @rules.map(&:id)
-      raise ConfigError, "#{source.path}: judgelint:disable names unknown rules #{unknown.join(', ')}" unless unknown.empty?
-
       questions = {}
-      suppressed = []
       rules.each do |rule|
         ranges = rule.ranges(source, Config::WINDOW_LINES).select { |first, last| touched?(lines, first, last) }
         next if ranges.empty?
 
-        kept = ranges.reject { |first, last| source.suppressed?(rule.id, first, last) }
-        if kept.empty?
-          suppressed << rule
-        else
-          asked = []
-          kept.each do |first, last|
-            asked << Question.new(rule, first, last)
-            asked << Question.new(rule, first, last, inverted: true) if rule.convention
-          end
-          questions[rule] = asked
+        asked = []
+        ranges.each do |first, last|
+          asked << Question.new(rule, first, last)
+          places = places(source, rule, first, last)
+          asked << Question.new(rule, first, last, kind: :where, places: places) unless places.empty?
+          asked << Question.new(rule, first, last, kind: :excuse) if source.hinted?(first, last)
         end
+        questions[rule] = asked
       end
-      job = Job.new(source, questions, suppressed, prose: rules.first&.prose, expected: expected)
+      job = Job.new(source, questions, prose: rules.first&.prose, expected: expected)
       pack(job)
       job
     end
 
+    # The options for asking where a bullet is broken: the range's line ids, or
+    # the directory's files. None for a rule written as a question, or past
+    # what a choice can hold.
+    def places(source, rule, first, last)
+      return [] unless rule.convention
+
+      places = rule.directory? ? source.members.map { |_path, shown| shown } : (first..last).map { |line| "L#{line}" }
+      places.size > MAX_OPTIONS ? [] : places
+    end
+
     # Rules that read different context files or spec prose can't share a request.
     def by_context(rules)
       rules.group_by { |rule| [rule.context, rule.prose] }.map { |(globs, _prose), group| yield(Glob.expand(globs), group) }
@@ -236,32 +257,87 @@ module Judgelint
     def verdicts(job)
       path = job.source.path
       found = job.questions.map { |rule, questions| verdict_for(rule, path, questions, job) }
-      found += job.suppressed.map { |rule| Verdict.new(rule: rule, path: path, probability: nil, status: :suppressed) }
       job.expected ? found.map { |verdict| verdict.as_example(job.expected) } : found
     end
 
-    # A window's probability of a violation is the average over its questions
-    # (a bullet is asked both ways) and the models; a rule's verdict is its
-    # worst window.
+    # A window's probability of a violation is the average of its verdict
+    # over the models, and its place is the line or file the models' "where"
+    # answers agree on. A rule's verdict is its worst window. A window whose
+    # judgehint excuses it, by the same average and threshold, is reported as
+    # excused instead, unless another window breaks the rule.
     def verdict_for(rule, path, questions, job)
       return Verdict.new(rule: rule, path: path, probability: nil, status: :skipped) if job.skipped
 
-      windows = []
+      open = []
+      excused = []
       questions.group_by { |question| [question.first, question.last] }.each do |(first, last), asked|
         values = []
+        excuses = []
+        spread = {}
         asked.each do |question|
           job.answers.each_value do |answers|
-            yes = answers[question.key]
-            values << question.violation(yes) unless yes.nil?
+            answer = answers[question.key]
+            next if answer.nil?
+
+            if question.excuse?
+              excuses << answer
+            elsif question.where?
+              answer.each { |place, probability| spread[place] = (spread[place] || 0.0) + probability }
+            else
+              values << question.violation(answer)
+            end
           end
         end
-        windows << [first, last, values.sum / values.size] unless values.empty?
+        next if values.empty?
+
+        window = Window.new(first, last, values.sum / values.size, agreed(spread))
+        if !excuses.empty? && excuses.sum / excuses.size >= rule.threshold
+          excused << window
+        else
+          open << window
+        end
       end
-      return Verdict.new(rule: rule, path: path, probability: nil, status: :refused) if windows.empty?
+      return Verdict.new(rule: rule, path: path, probability: nil, status: :refused) if open.empty? && excused.empty?
+
+      found = worst(rule, path, open, job.source)
+      return found if found && found.status != :pass
+
+      hidden = worst(rule, path, excused, job.source)
+      return found || hidden if hidden.nil? || hidden.status == :pass
+
+      Verdict.new(rule: rule, path: path, probability: hidden.probability, status: :excused, lines: hidden.lines,
+                  line: hidden.line, file: hidden.file)
+    end
 
-      first, last, probability = windows.max_by { |window| window[2] }
-      lines = rule.directory? ? nil : [first, last]
-      Verdict.classify(rule, path, probability, warn_at: @config.warn_at, lines: lines)
+    # The place with at least PLACE_AT of the summed "where" probabilities.
+    # A loop rather than max_by, which Spinel's Hash doesn't have yet.
+    def agreed(spread)
+      total = 0.0
+      best = nil
+      spread.each do |place, value|
+        total += value
+        best = place if best.nil? || value > spread[best]
+      end
+      return nil if total <= 0
+
+      spread[best] / total >= PLACE_AT ? best : nil
+    end
+
+    # The worst of +windows+, or nil if there are none.
+    def worst(rule, path, windows, source)
+      return nil if windows.empty?
+
+      window = windows.max_by(&:probability)
+      line = nil
+      file = nil
+      if rule.directory?
+        member = source.members.find { |_member, shown| shown == window.place }
+        file = member[0] if member
+      elsif window.place
+        line = window.place.delete_prefix("L").to_i
+      end
+      lines = rule.directory? ? nil : [window.first, window.last]
+      Verdict.classify(rule, path, window.probability, warn_at: @config.warn_at, lines: lines, line: line, file: file)
     end
 
     # Each model's answers are cached on their own, so adding a model asks

data/lib/judgelint/source.rb

@@ -5,14 +5,11 @@ module Judgelint
   # line numbered so a question can point at a range, followed by any context
   # files the rule names, which are there to read and never judged.
   #
-  # Inline suppressions turn a rule off where a person has decided the code is
-  # fine, and say why: a comment (#, //, --, /*, <!--, or ;) starting with
-  # `judgelint:disable <rule ids> -- <reason>` covers the window it falls in,
-  # and `judgelint:disable-file <rule ids> -- <reason>` covers the whole file.
-  # In a directory, either one covers the directory.
+  # A judgehint is a comment (#, //, --, /*, <!--, or ;) starting with
+  # `judgehint:` that says why the code is the way it is. The model weighs it
+  # for the window it falls in, or for the whole directory.
   class Source
-    SUPPRESSION = %r{(?:#|//|--|/\*|<!--|;)\s*judgelint:(disable-file|disable)\b(.*)\z}
-    REASONED = %r{\A\s+([A-Za-z0-9_./, -]+?)\s+--\s+\S}
+    HINT = %r{(?:#|//|--|/\*|<!--|;)\s*judgehint:}
 
     attr_reader :path, :shown_as, :line_count
 
@@ -28,9 +25,10 @@ module Judgelint
       @files = files.map { |file| [file, File.read(file).lines] }
       @context = context
       @line_count = @files.sum { |_file, lines| lines.size }
-      @disabled = {}
-      @disabled_file = []
-      @files.each { |file, lines| find_suppressions(file, lines) }
+      @hints = []
+      @files.each do |_file, lines|
+        lines.each_with_index { |line, index| @hints << index + 1 if HINT.match?(line) }
+      end
     end
 
     def directory?
@@ -56,15 +54,13 @@ module Judgelint
       (1..line_count).step(size).map { |first| [first, [first + size - 1, line_count].min] }
     end
 
-    def suppressed?(rule_id, first, last)
-      return true if @disabled_file.include?(rule_id)
-
-      lines = @disabled[rule_id] || []
-      directory? ? !lines.empty? : lines.any? { |line| line.between?(first, last) }
+    # The directory's files as [path, the path the model sees].
+    def members
+      @files.map { |file, _lines| [file, shown(file)] }
     end
 
-    def suppressed_ids
-      (@disabled.keys + @disabled_file).uniq
+    def hinted?(first, last)
+      directory? ? !@hints.empty? : @hints.any? { |line| line.between?(first, last) }
     end
 
     private
@@ -77,22 +73,5 @@ module Judgelint
     def shown(file)
       "#{shown_as}/#{file.delete_prefix("#{path}/")}"
     end
-
-    def find_suppressions(file, lines)
-      lines.each_with_index do |line, index|
-        match = SUPPRESSION.match(line.chomp)
-        next unless match
-
-        reasoned = REASONED.match(match[2])
-        raise ConfigError, "#{file}:#{index + 1}: judgelint:#{match[1]} needs rule ids and a reason after --" unless reasoned
-
-        ids = reasoned[1].split(/[\s,]+/).reject(&:empty?)
-        if match[1] == "disable-file"
-          @disabled_file.concat(ids)
-        else
-          ids.each { |id| (@disabled[id] ||= []) << index + 1 }
-        end
-      end
-    end
   end
 end

data/lib/judgelint/verdict.rb

@@ -5,55 +5,59 @@ module Judgelint
   #
   # +status+ is :violation (at or above the rule's threshold), :uncertain
   # (between warn_at and the threshold), :pass, :skipped (the file is too
-  # large to judge), :refused (the model declined the question), or
-  # :suppressed (a judgelint:disable comment covers it). Skipped and refused
-  # files are reported, never silently passed. +lines+ is the [first, last]
-  # range the verdict came from.
+  # large to judge), :refused (the model declined the question), or :excused
+  # (a violation or uncertain, but a judgehint excuses it). Skipped and
+  # refused files are reported, never silently passed. +lines+ is the [first,
+  # last] range the verdict came from. +line+ is the line in it that breaks
+  # the rule, and +file+ the file in a directory, when the model could say.
   #
   # An example's verdict also knows the answer it should have had: +expected+
   # is :pass or :fail for files under rules/<id>/pass and rules/<id>/fail.
   # Not Data.define: Spinel can't compile a Data or Struct in a program that also uses net/https and json.
   class Verdict
-    attr_reader :rule, :path, :probability, :status, :lines, :expected
+    attr_reader :rule, :path, :probability, :status, :lines, :line, :file, :expected
 
-    def initialize(rule:, path:, probability:, status:, lines: nil, expected: nil)
+    def initialize(rule:, path:, probability:, status:, lines: nil, line: nil, file: nil, expected: nil)
       @rule = rule
       @path = path
       @probability = probability
       @status = status
       @lines = lines
+      @line = line
+      @file = file
       @expected = expected
     end
 
     def as_example(expected)
-      Verdict.new(rule: rule, path: path, probability: probability, status: status, lines: lines, expected: expected)
+      Verdict.new(rule: rule, path: path, probability: probability, status: status, lines: lines, line: line, file: file,
+                  expected: expected)
     end
 
     # +probability+ is the probability the code breaks the rule.
-    def self.classify(rule, path, probability, warn_at:, lines: nil)
+    def self.classify(rule, path, probability, warn_at:, lines: nil, line: nil, file: nil)
       status =
         if probability >= rule.threshold then :violation
         elsif probability >= warn_at then :uncertain
         else :pass
         end
-      new(rule: rule, path: path, probability: probability, status: status, lines: lines)
+      new(rule: rule, path: path, probability: probability, status: status, lines: lines, line: line, file: file)
     end
 
     def failing?
       status == :violation && rule.error?
     end
 
-    # A refused, skipped, or suppressed example is a miss either way: the rule
-    # didn't work on it.
+    # A refused or skipped example is a miss either way: the rule didn't work
+    # on it. An excused one isn't a violation.
     def correct?
-      return false if %i[refused skipped suppressed].include?(status)
+      return false if %i[refused skipped].include?(status)
 
       (status == :violation) == (expected == :fail)
     end
 
     def to_h
       {
-        "path" => path, "lines" => lines, "rule" => rule.id, "severity" => rule.severity, "status" => status.to_s,
+        "path" => path, "lines" => lines, "line" => line, "file" => file, "rule" => rule.id, "severity" => rule.severity, "status" => status.to_s,
         "probability" => probability&.round(3), "message" => rule.message
       }.merge(expected ? { "expected" => expected.to_s, "correct" => correct? } : {})
     end

data/lib/judgelint/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Judgelint
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: judgelint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - JP Camara
@@ -10,10 +10,10 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: |
-  judgelint checks files against conventions that only a reader can judge. Each
-  rule is a yes/no question answered by a fast decision model such as TypeSafe's
-  Jev over the System One protocol. It also compiles to a native binary with
-  Spinel.
+  judgelint checks code against conventions you write as bullets in a README.
+  It asks a decision model, such as TypeSafe's Jev, whether each file breaks
+  each bullet, and reports violations with line numbers. On macOS and Linux
+  the gem includes a native binary.
 email:
 - johnpcamara@gmail.com
 executables:
@@ -69,6 +69,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Lint for conventions a linter can't check, judged by System One decision
+summary: Checks code against conventions written in plain English, using decision
   models.
 test_files: []