swarf 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c617f49a96d65792c3b8d3e2465effae7ad84b0c9b414770a4726cc0c8187165
-  data.tar.gz: 689601738e13957770d0a0c1a018e37507d5d563cc46688506f6162cc67d1367
+  metadata.gz: 07d2bf8d0f9950fa5da4bc574daa87e441966ece6477988a67c26bebe50c1df5
+  data.tar.gz: dfa6942db8ea5ca53a7859704052f325f72fe006b485a047a409ee4630881bb2
 SHA512:
-  metadata.gz: 1fdfdb2342066a65fa736103f9af0caa4472a35f444f80045ae1b88a17a1290904b1d86e610b9660cf75f2887bac4f4fbc4512c4a4ac28a09365a6fe3743545e
-  data.tar.gz: b2ae944731ba4966ce88b5abe117b61c8fe7563659274ab03e1834c3751501c7c8a8f53b2447959b7bb86c00061ee1338de8a1097698427d31ed840456b79da7
+  metadata.gz: 1a7bd9e64ef347c33bf744eeff23d3923e0a0f846ae12144438390ce27d46f24feb4e95f5f78854d627458184862c7a2bf9219632bdccf0ac115402c4df0210e
+  data.tar.gz: b328a085e7e4d7a88c58a9d48436ee37a561b83ff0a3c7596b4880780c1b0ab7d37f6b4fd6ab3470214e20b52a7b5f3bd8e14abad8ee57adf97abad5c5dd26c3

data/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+      - run: bundle exec rake

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0 — 2026-09-06
+
+- `swarf init` installs a Claude Code skill into `.claude/skills/swarf/` and adds
+  `.swarf/` to `.gitignore`.
+
+## 0.1.0 — 2026-09-05
+
+Initial release.

data/CONTEXT.md

@@ -1,6 +1,6 @@
 # Domain language
 
-Terms used in swarf's code, tests and commit messages. The README splits swarf into two halves that never talk to each other: the **probe**, which records coverage from inside your test process, and the **runner**, which scores. The terms below name the parts of the runner.
+Terms used in swarf's code, tests and commit messages. The README splits swarf into a **probe** and a **runner**. The terms below name the parts of the runner.
 
 ## Scan
 
@@ -12,4 +12,4 @@ A scan owns no I/O policy — it is given its paths, its ignore patterns, its st
 
 What test runs recorded about one file: line hits, branch outcomes, method call counts, and the SHA-256 of the bytes those numbers were measured against.
 
-A measurement knows whether it still describes the file on disk. It answers that question the first time it is asked and remembers the answer — asked before the source is read, it would report bytes the scan never saw, which is the confidently-wrong staleness DESIGN §4 exists to prevent.
+A measurement knows whether it still describes the file on disk. It answers that question the first time it is asked and remembers the answer — asked before the source is read, it would report bytes the scan never saw, which is the confidently-wrong staleness the SHA-256 check exists to prevent.

data/README.md

@@ -1,6 +1,10 @@
 # swarf
 
-Scores every Ruby method by how complex it is against how well your tests actually exercise it.
+Ask an agent to improve a codebase and it will keep going. There is always another name to argue with, another method to rearrange, and nothing in the loop that says when the returns have run out. We bikeshed the same way; the difference is that the agent bills you for it.
+
+The CRAP score is one way out. It folds test coverage into complexity instead of measuring complexity alone: complexity sets the floor, and coverage is the only thing that brings the number down. So a hairy method the tests cover well scores as low as it can and drops off the list, while an untested one stays at the top. That ordering is the signal — it says which code is actually worth spending tokens on.
+
+swarf scores every method in a Ruby or Rails codebase this way, worst first.
 
 ```
 $ swarf lib/
@@ -26,11 +30,9 @@ Complexity is squared; the _uncovered_ fraction is cubed. Two identities explain
 | 100%     | `CC`       | fully tested code is only as risky as it is complex |
 | 0%       | `CC² + CC` | untested complexity grows quadratically             |
 
-The curve is nearly flat near full coverage and violently steep near zero, which is the
-point: simple code and small gaps stay quiet, complex code nobody has run scores loudly.
+The curve is nearly flat near full coverage and steep near zero: simple code and small gaps stay quiet, complex code nobody has run scores loudly.
 
-From Alberto Savoia and Bob Evans (2007), where it stood for _Change Risk Analysis and
-Prediction_; Robert C. Martin's ports expand it as _Change Risk Anti-Pattern_. Same formula.
+From Alberto Savoia and Bob Evans (2007), where it stood for _Change Risk Analysis and Prediction_; Robert C. Martin's ports expand it as _Change Risk Anti-Pattern_. Same formula.
 
 ## Install
 
@@ -43,6 +45,16 @@ gem "swarf", group: :development
 $ bundle install
 ```
 
+Working with Claude Code? Install the skill that teaches it the loop below, so it scores
+the files it touched and writes the test the top row asks for:
+
+```
+$ bundle exec swarf init
+```
+
+That writes `.claude/skills/swarf/` and adds `.swarf/` to `.gitignore`. Commit both.
+Run it again after upgrading the gem to refresh the skill.
+
 ## Getting started
 
 ### 1. Score complexity — no setup at all
@@ -62,9 +74,7 @@ Cart#subtotal    1     —   2.00   no data  lib/cart.rb:11
 No coverage recorded for every file — run your suite with swarf/probe loaded.
 ```
 
-`no data` means no test run has been recorded yet, so every method reports `CC² + CC`.
-That is not a placeholder — it is the correct score for code nothing has run. Adding
-coverage can only ever pull a number _down_, toward `CC`.
+`no data` means no test run has been recorded yet, so every method reports `CC² + CC`. That is the correct score for code nothing has run. Adding coverage can only ever pull a number _down_, toward `CC`.
 
 ### 2. Record coverage — one line
 
@@ -90,8 +100,7 @@ Minitest::TestTask.create do |t|
 end
 ```
 
-**Rails** — in `test/test_helper.rb`, above `config/environment`, or the whole app loads
-before the probe does and none of it is measured:
+**Rails** — in `test/test_helper.rb`, above `config/environment`, or the whole app loads before the probe does and none of it is measured:
 
 ```ruby
 ENV["RAILS_ENV"] ||= "test"
@@ -102,9 +111,7 @@ require "swarf/probe"
 require_relative "../config/environment"
 ```
 
-`bundler/setup` is only what `config/boot` would do anyway; the probe needs it to find the
-gem this early. Rails parallelises tests by forking, which swarf handles — every worker
-merges into the store under a lock.
+`bundler/setup` is only what `config/boot` would do anyway; the probe needs it to find the gem this early. Rails parallelises tests by forking, which swarf handles — every worker merges into the store under a lock.
 
 **Anything else** — set it on the command line, no files to edit:
 
@@ -112,8 +119,7 @@ merges into the store under a lock.
 $ RUBYOPT="-rswarf/probe" bundle exec rake test
 ```
 
-Order matters and is not negotiable: `Coverage` measures only files loaded _after_ it
-starts. Put the probe under your application and the application is invisible to it.
+`Coverage` measures only files loaded _after_ it starts. Put the probe under your application and the application is invisible to it.
 
 Then ignore the store:
 
@@ -136,8 +142,7 @@ Cart#shipping    3   66.7%   3.33        2/3 br  lib/cart.rb:15
 Cart#subtotal    1  100.0%   1.00        1/1 ln  lib/cart.rb:11
 ```
 
-Every run merges into `.swarf/coverage.json`, so partial runs are fine — running one spec
-file does not erase what another proved. Your runs, CI's runs and a colleague's all add up.
+Every run merges into `.swarf/coverage.json`, so partial runs are fine — running one spec file does not erase what another proved. Your runs, CI's runs and a colleague's all add up.
 
 ## Reading the report
 
@@ -148,7 +153,7 @@ file does not erase what another proved. Your runs, CI's runs and a colleague's
 | `CRAP`     | the score; worst first                                            |
 | `Evidence` | where the coverage number came from, so you know what to do next  |
 
-The evidence column is the actionable half:
+The evidence column tells you what to do next:
 
 | evidence       | what it means                               | what to do                           |
 | -------------- | ------------------------------------------- | ------------------------------------ |
@@ -160,8 +165,7 @@ The evidence column is the actionable half:
 
 Both `no data` and `stale` fall back to the `CRAP = CC² + CC` floor rather than guessing.
 
-Those two also print under the table, counted by file, because the fix is per file rather
-than per method:
+Those two also print under the table, counted by file, because the fix is per file rather than per method:
 
 ```
 … 45 more (--limit 0 for all)
@@ -174,20 +178,19 @@ A fully measured project prints neither line.
 ## Command line
 
 ```
-$ swarf                       # the whole project
-$ swarf lib/ app/             # directories, recursively
-$ swarf lib/app/cart.rb       # a single file
-$ swarf --limit 50            # show 50 rows instead of 20
-$ swarf --limit 0             # show everything
-$ swarf --ignore "app/legacy/**"   # skip a path (repeatable)
-$ swarf --all                 # score everything, ignoring nothing
+$ swarf                             # the whole project
+$ swarf lib/ app/                   # directories, recursively
+$ swarf lib/app/cart.rb             # a single file
+$ swarf --limit 50                  # show 50 rows instead of 20
+$ swarf --limit 0                   # show everything
+$ swarf --ignore "app/legacy/**"    # skip a path (repeatable)
+$ swarf --all                       # score everything, ignoring nothing
+$ swarf init                        # install the Claude Code skill, ignore .swarf/
 $ swarf --version
 $ swarf --help
 ```
 
-Only the worst 20 rows print by default, with a count of what was held back. A 245-file
-project reports 344 methods, and the tail of that list is all `CRAP 1.00` — noise that
-buries the handful of rows worth acting on.
+Only the worst 20 rows print by default, with a count of what was held back. A 245-file project reports 344 methods, and the tail of that list is all `CRAP 1.00` — noise that buries the handful of rows worth acting on.
 
 ## What gets skipped
 
@@ -197,9 +200,7 @@ db/**                                      migrations and schema
 **/vendor/**  **/tmp/**  **/log/**  **/node_modules/**
 ```
 
-Migrations matter more than they look. They are generated, run once and never tested, so
-on a well-tested codebase they are the only untested code left and they take over the top
-of the report — on a 20-file Rails app they ranked 3rd, 4th and 5th.
+Migrations matter more than they look. They are generated, run once and never tested, so on a well-tested codebase they are the only untested code left and they take over the top of the report — on a 20-file Rails app they ranked 3rd, 4th and 5th.
 
 Add your own in `.swarfignore` at the project root, one glob per line:
 
@@ -209,12 +210,9 @@ lib/api/generated_client.rb
 app/legacy/**
 ```
 
-Patterns match against each file's path relative to the directory being scanned, and both
-`*` and `**` cross directories. Naming a path on the command line always wins, so
-`swarf db/migrate` scores migrations even though `db/**` is a default.
+Patterns match against each file's path relative to the directory being scanned, and both `*` and `**` cross directories. Naming a path on the command line always wins, so `swarf db/migrate` scores migrations even though `db/**` is a default.
 
-Directories are searched for `**/*.rb`, skipping `test/`, `spec/`, `vendor/`, `tmp/` and
-`node_modules/`. Naming one of those directly still scores it.
+Directories are searched for `**/*.rb`, skipping `test/`, `spec/`, `vendor/`, `tmp/` and `node_modules/`. Naming one of those directly still scores it.
 
 `SWARF_DIR` moves the coverage store, which both the probe and the runner must agree on:
 
@@ -241,54 +239,30 @@ flowchart LR
     Score --> Report["report, worst first"]
 ```
 
-The probe is about thirty lines: `Coverage.start` plus an `at_exit` that dumps the result.
-The runner never loads your application — it parses text.
+The probe is twenty lines: `Coverage.start` plus an `at_exit` that dumps the result. The runner never loads your application — it parses text.
 
 ## Things worth knowing
 
-**Coverage needs a run; complexity does not.** Nothing static can tell you whether a line
-executed. Any run counts, not just specs — a rake task, booting the app, a script.
-
-**The probe must load first.** `Coverage` only measures files loaded after it starts. Put
-it ahead of your application, or the application is invisible to it.
+**Any run counts, not just specs.** A rake task, booting the app or a script all record coverage; nothing static can tell you whether a line executed.
 
-**swarf and SimpleCov cannot both run.** Ruby permits one `Coverage.start` per process. If
-SimpleCov gets there first, swarf warns and records nothing rather than killing your suite.
+**swarf and SimpleCov cannot both run.** Ruby permits one `Coverage.start` per process. If SimpleCov gets there first, swarf warns and records nothing rather than killing your suite.
 
-**Branch coverage is preferred, with a line fallback.** Ruby puts a decision on a line that
-runs whichever way the decision goes, so `return 0 if x.negative?` reads 100% by line even
-when the guard never fires — maximally wrong exactly where risk collects. Methods with no
-branches fall back to lines, where "did it run" is the whole truth.
+**Branch coverage is preferred, with a line fallback.** Ruby puts a decision on a line that runs whichever way the decision goes, so `return 0 if x.negative?` reads 100% by line even when the guard never fires — wrong exactly where risk collects. Methods with no branches fall back to lines, where "did it run" is the whole truth.
 
-**`never called` is a fact, not an inference.** It comes from a VM-level call count. It
-tells you to _write_ a test; `3/6 br` tells you to _extend_ one. A bare `0.0%` tells you
-neither.
+**`never called` comes from a VM-level call count.** It tells you to _write_ a test; `3/6 br` tells you to _extend_ one. A bare `0.0%` tells you neither.
 
-**Edited files report `no coverage`, not stale numbers.** Coverage is indexed by line
-number, so inserting a method at the top of a file shifts every line below it while the
-counters stay put. swarf stores a SHA-256 per measured file and drops entries whose bytes
-changed, because stale coverage is worse than none — it is confidently wrong.
+**Edited files report `no coverage`, not stale numbers.** Coverage is indexed by line number, so inserting a method at the top of a file shifts every line below it while the counters stay put. swarf stores a SHA-256 per measured file and drops entries whose bytes changed, because stale coverage is confidently wrong.
 
-**swarf's CC will not match RuboCop's.** It counts `if`, `unless`, `while`, `until`, `for`,
-each `when`, each `in`, each `rescue`, `&&`, `||` and `&.` — **not blocks**. Six chained
-`add_option` blocks are not six decisions. The trade-off is that CC largely ignores
-iteration, since Ruby iterates with blocks.
+**swarf's CC will not match RuboCop's.** It counts `if`, `unless`, `while`, `until`, `for`, each `when`, each `in`, each `rescue`, `&&`, `||` and `&.` — **not blocks**. Six chained `add_option` blocks are not six decisions. The trade-off is that CC largely ignores iteration, since Ruby iterates with blocks.
 
-**There is no threshold and nothing fails.** swarf sorts worst-first and prints. Because
-`CRAP = CC` at full coverage, a fixed threshold is a complexity cap in disguise — a method
-at CC 9 can never score under 9 however well you test it, and the only remaining move is to
-split it. Ranking is enough; capping complexity is RuboCop's job.
+**There is no threshold and nothing fails.** swarf sorts worst-first and prints. Because `CRAP = CC` at full coverage, a fixed threshold is a complexity cap in disguise — a method at CC 9 can never score under 9 however well you test it, and the only remaining move is to split it. Ranking is enough; capping complexity is RuboCop's job.
 
 ## Known limitations
 
-- Methods defined inside a `Struct.new do ... end` block take the enclosing module's name
-  (`Swarf#crap` rather than `Swarf::Score#crap`), because the block is not a class node.
-- `define_method` and other dynamically defined methods are not seen at all — swarf reads
-  `def`.
-- Nested `def`s get their own complexity, but the outer method's coverage still counts the
-  inner method's lines and branches.
-- Methods inside `class << self` are named correctly; methods defined by `instance_eval` or
-  a reopened singleton via a variable are not.
+- Methods defined inside a `Struct.new do ... end` block take the enclosing module's name (`Swarf#crap` rather than `Swarf::Score#crap`), because the block is not a class node.
+- `define_method` and other dynamically defined methods are not seen at all — swarf reads `def`.
+- Nested `def`s get their own complexity, but the outer method's coverage still counts the inner method's lines and branches.
+- Methods inside `class << self` are named correctly; methods defined by `instance_eval` or a reopened singleton via a variable are not.
 
 ## Development
 
@@ -308,5 +282,6 @@ $ ruby -Ilib exe/swarf lib/
 
 1. Update the version in `lib/swarf/version.rb`
 2. Run `bundle install` to update the lockfile
-3. Commit: `git commit -am "Release vX.Y.Z"`
-4. Run `bundle exec rake release` (builds the gem, creates the git tag, pushes to RubyGems)
+3. Move the `Unreleased` entries in `CHANGELOG.md` under the new version and date
+4. Commit: `git commit -am "Release vX.Y.Z"`
+5. Run `bundle exec rake release` (builds the gem, creates the git tag, pushes to RubyGems)

data/Rakefile

@@ -5,8 +5,6 @@ require "minitest/test_task"
 require "standard/rake"
 
 Minitest::TestTask.create do |task|
-  # Record swarf's coverage with swarf. The prelude runs before the tests load,
-  # which is the only place `Coverage.start` can still see them.
   task.test_prelude = 'require "swarf/probe"'
 end
 

data/exe/swarf

@@ -4,4 +4,8 @@
 
 require "swarf"
 
-exit Swarf::CLI.run(ARGV)
+begin
+  Swarf::CLI.run(ARGV)
+rescue Swarf::Error => e
+  abort "swarf: #{e.message}"
+end

data/lib/swarf/cli.rb

@@ -4,11 +4,8 @@ require "optparse"
 
 module Swarf
   class CLI
-    def self.run(argv, out: $stdout, err: $stderr)
-      new(argv).run(out)
-    rescue Error => e
-      err.puts("swarf: #{e.message}")
-      1
+    def self.run(argv, out: $stdout)
+      (argv == ["init"]) ? Init.new.run(out) : new(argv).run(out)
     end
 
     def initialize(argv)
@@ -21,7 +18,6 @@ module Swarf
     def run(out)
       scores = Scan.new(paths: @paths, ignore: ignore).scores
       out.print Report.new(scores, limit: @limit).to_s
-      0
     end
 
     private
@@ -34,7 +30,10 @@ module Swarf
 
     def parse(argv)
       parser = OptionParser.new do |opts|
-        opts.banner = "Usage: swarf [options] [paths]"
+        opts.banner = <<~USAGE
+          Usage: swarf [options] [paths]
+                 swarf init    Install the Claude Code skill and ignore .swarf/
+        USAGE
         opts.on("-n", "--limit N", Integer, "Rows to show (0 for all, default #{Report::DEFAULT_LIMIT})") do |n|
           @limit = n
         end

data/lib/swarf/init.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Swarf
+  class Init
+    SKILL_SOURCE = File.expand_path("../../skills/swarf", __dir__)
+    SKILL_TARGET = File.join(".claude", "skills", "swarf")
+    GITIGNORE_ENTRY = ".swarf/"
+
+    def initialize(root = Dir.pwd)
+      @root = root
+    end
+
+    def run(out)
+      out.puts "#{install_skill} #{SKILL_TARGET}/"
+      out.puts "#{ignore_store} #{GITIGNORE_ENTRY} in .gitignore"
+    end
+
+    private
+
+    def install_skill
+      target = File.join(@root, SKILL_TARGET)
+      existed = File.directory?(target)
+      FileUtils.mkdir_p(target)
+      FileUtils.cp_r(File.join(SKILL_SOURCE, "."), target)
+      existed ? "updated" : "wrote"
+    end
+
+    def ignore_store
+      path = File.join(@root, ".gitignore")
+      lines = File.exist?(path) ? File.readlines(path, chomp: true) : []
+      return "kept" if lines.any? { |line| line.strip.delete_suffix("/") == GITIGNORE_ENTRY.delete_suffix("/") }
+
+      File.write(path, [*lines, GITIGNORE_ENTRY].join("\n") + "\n")
+      "added"
+    end
+  end
+end

data/lib/swarf/report.rb

@@ -24,9 +24,6 @@ module Swarf
 
     def held_back = @scores.size - @shown.size
 
-    # Notes the reader can act on, each named for the move it asks for. Kept out of the
-    # rows because the action is per file, not per method: a project nothing has run is
-    # one sentence, not one row per method.
     def footer
       notes = []
       notes << "… #{held_back} more (--limit 0 for all)" if held_back.positive?

data/lib/swarf/version.rb

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

data/lib/swarf.rb

@@ -9,17 +9,13 @@ require_relative "swarf/score"
 require_relative "swarf/report"
 require_relative "swarf/sources"
 require_relative "swarf/scan"
+require_relative "swarf/init"
 require_relative "swarf/cli"
 
 module Swarf
   class Error < StandardError; end
 
   # CRAP(m) = CC(m)^2 * (1 - coverage(m))^3 + CC(m)
-  #
-  # Complexity is squared; the *uncovered* fraction is cubed. The score is
-  # nearly flat near full coverage and violently steep near zero, so simple
-  # code and small gaps stay quiet while complex code nothing has run scores
-  # loudly.
   def self.crap(complexity, coverage)
     (complexity**2) * ((1.0 - coverage)**3) + complexity
   end

data/skills/swarf/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: swarf
+description: Score Ruby methods by complexity against test coverage with swarf, and turn the worst rows into the next test to write. Use after writing or changing Ruby code and before calling a change done.
+---
+
+# swarf
+
+swarf scores every Ruby method with `CRAP = CC² · (1 − coverage)³ + CC` and lists them worst first. Complexity is parsed from source. Coverage is recorded by a probe loaded into the test run and stored in `.swarf/coverage.json`, so scoring works without setup but coverage needs a test run.
+
+## The loop
+
+1. Run the suite with the probe loaded (see Setup if unsure):
+
+   ```
+   bundle exec rspec          # or: bundle exec rake test
+   ```
+
+2. Score the files you touched, not the whole project:
+
+   ```
+   git diff --name-only --diff-filter=d main -- '*.rb' | xargs bundle exec swarf
+   ```
+
+   Named paths are always scored, even under `test/`, `db/` or a `.swarfignore` pattern.
+
+3. Take the top rows and act on the Evidence column (next section). Write or extend the test, re-run the suite, score again.
+
+4. Stop when the touched methods sit at `CRAP = CC` with `Cov% 100.0`. Nothing you test pulls a score under its CC. If a score is too high at full coverage, that is complexity, which is a refactor question, not a testing one. Do not split methods to chase the number.
+
+Before saying a change is done, run step 2 and report the top rows.
+
+## Reading a row
+
+```
+Method          CC    Cov%   CRAP      Evidence  Location
+Cart#checkout    6    0.0%  42.00  never called  lib/cart.rb:31
+Cart#discount    4   50.0%   6.00        3/6 br  lib/cart.rb:24
+```
+
+| Evidence       | Meaning                                      | Do                                                            |
+| -------------- | -------------------------------------------- | ------------------------------------------------------------- |
+| `never called` | A VM call count of zero. No test reaches it. | Write a test that calls it.                                   |
+| `3/6 br`       | 3 of 6 branch outcomes ran.                  | Extend a test to the untaken outcomes.                        |
+| `1/1 ln`       | No branches, so lines are the whole truth.   | Nothing, at 100%.                                             |
+| `no data`      | No run has been recorded for this file.      | The probe is not loaded, or the suite has not run. Fix Setup. |
+| `stale`        | The file changed after it was measured.      | Re-run the suite, then score again.                           |
+
+`no data` and `stale` both score at the `CC² + CC` floor rather than guess. They are also counted per file under the table, because the fix is per file.
+
+A `never called` on a method a test clearly exercises means the test ran without the probe, or the probe loaded after the file. Check Setup before writing a duplicate test.
+
+## Setup
+
+The probe must load before the code under test, because `Coverage` only sees files loaded after it starts. One line, placed first:
+
+- **RSpec**: first line of `.rspec`: `--require swarf/probe`
+- **Minitest**: first line of `test/test_helper.rb`: `require "swarf/probe"`
+- **Rails**: in `test/test_helper.rb`, after `require "bundler/setup"` and before `require_relative "../config/environment"`. Below the environment require, the whole app is invisible to it.
+- **Anything**: `RUBYOPT="-rswarf/probe" bundle exec rake test`
+
+Add `.swarf/` to `.gitignore`. Runs merge, so a single spec file adds to what earlier runs proved; nothing is erased until the file's bytes change.
+
+Do not run swarf's probe alongside SimpleCov. Ruby allows one `Coverage.start` per process; if SimpleCov started first, swarf warns and records nothing.
+
+## Commands
+
+```
+bundle exec swarf                       # whole project, worst 20
+bundle exec swarf lib/ app/             # directories
+bundle exec swarf app/models/cart.rb    # one file
+bundle exec swarf --limit 0             # every row
+bundle exec swarf --ignore "app/legacy/**"
+bundle exec swarf --all                 # ignore nothing, including db/ and .swarfignore
+SWARF_DIR=/tmp/swarf bundle exec swarf  # store elsewhere; set for the test run too
+```
+
+swarf's CC counts `if`, `unless`, `while`, `until`, `for`, `when`, `in`, `rescue`, `&&`, `||` and `&.`, not blocks, so it will not match RuboCop's. Methods made by `define_method` are not seen.

data/swarf.gemspec

@@ -14,6 +14,7 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = ">= 3.4.0"
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
 
   spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
     ls.readlines("\x0", chomp: true).reject do |f|

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: swarf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ariel Rzezak
@@ -17,8 +17,10 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/ci.yml"
 - ".standard.yml"
 - ".swarfignore"
+- CHANGELOG.md
 - CONTEXT.md
 - README.md
 - Rakefile
@@ -27,6 +29,7 @@ files:
 - lib/swarf/cli.rb
 - lib/swarf/complexity.rb
 - lib/swarf/coverage_map.rb
+- lib/swarf/init.rb
 - lib/swarf/measurement.rb
 - lib/swarf/probe.rb
 - lib/swarf/report.rb
@@ -35,12 +38,14 @@ files:
 - lib/swarf/sources.rb
 - lib/swarf/store.rb
 - lib/swarf/version.rb
+- skills/swarf/SKILL.md
 - swarf.gemspec
 homepage: https://github.com/arzezak/swarf
 licenses: []
 metadata:
   homepage_uri: https://github.com/arzezak/swarf
   source_code_uri: https://github.com/arzezak/swarf
+  changelog_uri: https://github.com/arzezak/swarf/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib