veragem 0.1.0 → 0.2.0

data/template/CONTRIBUTING.md.erb

@@ -2,8 +2,6 @@
 
 Thank you for considering contributing to `<%= name %>`!
 
-A project just generated: start at [First steps](#first-steps), under Maintainers.
-
 ## Prerequisites
 
 Either **Nix** -- `nix develop` gives Ruby and every tool below at the versions `flake.lock` pins
@@ -12,7 +10,7 @@ CI (nixpkgs packages few of them, and older).
 
 - **[Ruby](https://www.ruby-lang.org) 4.0** or later, with Bundler (Ruby's own). `bin/setup`
   installs the gems `Gemfile.lock` pins: Rake, RuboCop, its extensions and rubydex (its project
-  index), Steep, TypeProf, Minitest, SimpleCov, pbt, bundler-audit.
+  index), Steep, TypeProf, Minitest, SimpleCov, pbt, mutineer, YARD, yard-lint, bundler-audit, IRB.
 - **[ShellCheck](https://www.shellcheck.net/)** and **[shfmt](https://github.com/mvdan/sh)** --
   the shell's linter and formatter (its style is `.editorconfig`'s).
 - **[actionlint](https://github.com/rhysd/actionlint)** -- lints the workflows (and, through
@@ -20,10 +18,13 @@ CI (nixpkgs packages few of them, and older).
 - **[zizmor](https://docs.zizmor.sh/)** -- audits the workflows' security, and Dependabot's
   configuration.
 - **[dprint](https://dprint.dev/)** -- formats the Markdown and TOML.
-- **[cocogitto](https://docs.cog.tools/)** (`cog`) -- enforces Conventional Commits.
+- **[cocogitto](https://docs.cocogitto.io/)** (`cog`) -- enforces Conventional Commits.
 - **[git-cliff](https://git-cliff.org/)** -- writes the changelog at a release.
+- **[lychee](https://lychee.cli.rs/)** -- checks the links of the files git tracks but the
+  tests', online (`rake links`; `links.yml` monthly too).
 - **[Nix](https://nixos.org)** for the last of `rake checks`, the flake's checks (`rake nix`):
-  without it, `rake checks` stops there, every other check passed.
+  without it, `rake checks` stops there, every other check passed. `rake format` needs it too, for
+  `nix fmt`, before shfmt and RuboCop.
 
 ## Setup
 
@@ -36,14 +37,15 @@ bin/setup
 ```
 
 3. Optionally, `bundle exec rake hooks`: `.githooks/` then runs RuboCop, the shell, the workflows
-   and dprint before each commit, checks its message as a Conventional Commit, and every pushed
-   commit's message before a push: what CI would refuse, minutes earlier.
+   and dprint before each commit, checks its message as a Conventional Commit, and each commit's
+   in a pushed ref's history before a push: what CI would refuse, minutes earlier.
    `git config --unset core.hooksPath` turns them off.
 
 ## Guidelines
 
-Before you start, read [AGENTS.md](AGENTS.md): the lint and type policy, and what to do when a
-cop or a diagnostic fires. It applies to human and AI-assisted contributions alike.
+Before you start, read [AGENTS.md](AGENTS.md): the lint and type policy, what to do when a cop or a
+diagnostic fires, the comments, the commits, and what a change passes before it is done. It applies
+to human and AI-assisted contributions alike.
 
 ## Testing
 
@@ -53,8 +55,21 @@ cop or a diagnostic fires. It applies to human and AI-assisted contributions ali
   `Pbt.assert { Pbt.property(...) { ... } }`): it is checked on many generated inputs, and a
   failure is shrunk to its smallest counterexample, with the seed that reproduces it.
 - **Regressions:** if you are fixing a bug, include a test that reproduces the previous failure.
-- **Coverage:** every line, branch and method of `lib/` (SimpleCov's `strict` profile,
-  `test/test_helper.rb`). Code a test cannot reach is questioned before it is excluded.
+- **Coverage:** every line, branch and method of `lib/` (SimpleCov's `strict` profile, configured in
+  `.simplecov`, started by `rake test`). Code no test needs is deleted, not excluded (AGENTS.md,
+  §4). Some tests alone (`bundle exec rake test N=/version/`) fail the gate (exit 2) though they
+  pass: Minitest's verdict is printed above SimpleCov's. One file run alone is not measured, its
+  warnings raised as `rake test` raises them (the helper first, before the file is parsed):
+  `bundle exec ruby -w -Ilib -Itest -rtest_helper test/test_<%= underscored %>.rb`.
+- **Warnings:** one from `lib/` or the tests fails them, every category of Ruby's on
+  (`test/test_helper.rb`); a gem's only prints.
+- **Mutations:** `bundle exec rake mutation` changes `lib/` a mutant at a time (mutineer,
+  `.mutineer.yml`) and lists each one no test catches: a test missing, or a change that keeps the
+  behaviour, which `.mutineer.yml`'s `ignore:` holds with its reason. One survivor fails it
+  (`threshold: 100`). It takes minutes: `rake checks` mutates the lines changed since `origin/main`
+  alone (`rake mutation:changed`; all of them where there is none), and `ruby-ci.yml` every line.
+  Each first fails on an ignore that names no mutant (`rake mutation:ignores`): its method changed
+  or moved, so it hides nothing.
 
 ## Development Workflow
 
@@ -64,14 +79,18 @@ cop or a diagnostic fires. It applies to human and AI-assisted contributions ali
 2. Run the checks. The Rakefile runs the workflows' commands:
 
 ```sh
-bundle exec rake          # RuboCop, Steep, the tests: ruby-ci.yml
-bundle exec rake checks   # and bundler-audit, dprint, cog, the shell, the workflows, the flake's checks
-bundle exec rake format   # RuboCop's corrections, dprint and nixfmt, in place
-bundle exec rake typeprof # the signatures TypeProf infers from lib/, to start sig/ from
-nix build                 # the gem, built and installed by Nix (flake.nix)
+bundle exec rake                 # RuboCop, Steep, the tests, yard-lint: ruby-ci.yml
+bundle exec rake checks          # and bundler-audit, dprint, cog, the shell, the workflows, the
+                                 # links, the changed lines' mutations, the flake's checks
+bundle exec rake rubocop:changed # RuboCop on the files changed since origin/main
+bundle exec rake format          # dprint, nixfmt, shfmt and RuboCop's corrections, in place
+bundle exec rake typeprof        # the signatures TypeProf infers from lib/, to start sig/ from
+bundle exec rake yard            # the documentation of lib/, in doc/
+bundle exec rake graph           # its classes and modules, for Graphviz: | dot -Tsvg -o graph.svg
+nix build                        # the gem, built and installed by Nix (flake.nix)
 ```
 
-`bundle exec rake -T` lists every task.
+`bundle exec rake -T` lists every task, and `bundle exec rake -D` describes each in full.
 
 A new dependency of the gem goes in the gemspec (`spec.add_dependency`), and, for the Nix package,
 its nixpkgs package in flake.nix's `dependencies` (`pkgs.rubyPackages_4_0.<gem>`): the flake's
@@ -81,7 +100,8 @@ new tool goes in the Gemfile, which the built gem never holds: its dependencies
 alone. `bundle install` then updates the lock. Steep reads a library's signatures when the
 Steepfile names it (`library "json"`): the standard library's, and a gem's own (its `sig/`). A gem
 that ships none may have them in gem_rbs_collection, read through an RBS collection
-(`rbs collection init`, then `rbs collection install`, as rbs's `docs/collection.md` describes).
+(`rbs collection init`, then `rbs collection install`, as rbs's `docs/collection.md` describes;
+`steep check` installs it from the committed lock where it is missing, as in CI).
 
 ## Creating a Pull Request
 
@@ -115,24 +135,45 @@ Then, in whichever order suits you:
   `.github/workflows/dependabot-automerge.yml`: without required status checks, it merges bumps
   that CI never gated.
 - Enable private vulnerability reporting (Settings → Advanced Security; a public repository's
-  alone): it is off by default, and [SECURITY.md](SECURITY.md) and the issue form point to it.
+  alone): it is off by default, and [SECURITY.md](SECURITY.md) and the issue chooser's link point
+  to it.
 - Enable the dependency graph (Settings → Advanced Security), if it is off: the dependency review
   (`dependency-review.yml`) fails without it. A private repository's needs GitHub Code Security
   too, an organization's; without it, delete the workflow.
-- Add a pending trusted publisher on [RubyGems](https://rubygems.org/profile/oidc/pending_trusted_publishers)
-  for the gem `<%= name %>`: this repository, the workflow `release.yml`, the environment
-  `release`. A release tag then publishes without a stored key, its first version too, and its
-  GitHub release follows RubyGems': without the publisher, neither is made.
-- If you limit the `release` environment's deployments (Settings → Environments), admit the
-  release tags, a rule of ref type Tag, `v*`: the RubyGems job runs on the tag, and an environment
-  that refuses it publishes nothing.
+- Add a pending trusted publisher on
+  [RubyGems](https://rubygems.org/profile/oidc/pending_trusted_publishers) for the gem
+  `<%= name %>`: this repository, the workflow `release.yml`, the environment `release` (a
+  publisher without one admits any of the workflow's jobs, its signing job's too). A release tag
+  then publishes without a stored key, its first version too, and its GitHub release follows
+  RubyGems': without the publisher, neither is made.
+- Limit the `release` environment's deployments to the release tags (Settings → Environments, a
+  rule of ref type Tag, `v*`): a trusted publisher names the environment, not a ref, so without the
+  rule a workflow pushed to any branch could publish the gem. And limit who creates the release tags
+  (Settings → Rules → Rulesets, a tag ruleset on `v*`): a tag pushed on any commit runs that
+  commit's workflows in the environment.
 <%- if exe -%>
 - After the first release, make the image public: GHCR publishes a new package as private (its
   page, Package settings → Change visibility).
+- Limit the `image` environment's deployments to the release tags as well (a rule of ref type Tag,
+  `v*`): its jobs push the image.
 - To publish the image to Docker Hub too: create its repository there, then set the repository
-  variable `DOCKERHUB_USERNAME` and the secret `DOCKERHUB_TOKEN` (an access token that writes) --
-  and the variable `DOCKERHUB_REPOSITORY` (`namespace/name`) unless it is `<username>/<%= name %>`.
-  A Docker Hub failure in the build (its login, its name, a push) holds GHCR's tag back too.
+  variable `DOCKERHUB_USERNAME` and the `image` environment's secret `DOCKERHUB_TOKEN` (an access
+  token that writes; only the environment's jobs, on a release tag, can read it) -- and the variable
+  `DOCKERHUB_REPOSITORY` (`namespace/name`) unless it is `<username>/<%= name %>`. A Docker Hub
+  failure in a push (its login, its name) holds GHCR's tag back too.
+<%- end -%>
+<%- if citation -%>
+- To archive each release with a DOI, enable the repository on [Zenodo](https://zenodo.org) (its
+  profile menu → GitHub, the repository's toggle): a GitHub release, `release.yml`'s, is then
+  archived, its metadata `CITATION.cff`'s. After the first, uncomment the DOIs at the end of
+  `CITATION.cff` and set them: the concept DOI, which names every version (Zenodo's "Cite all
+  versions") and which GitHub's citation then links, and a release's own, which Zenodo mints only
+  after its tag, so the file can name an earlier version's alone.
+<%- unless licenses.one? -%>
+  Zenodo's import refuses `CITATION.cff`'s list of licences, the Citation File Format's OR, so
+  it archives no release until
+  [zenodo/zenodo-rdm#1509](https://github.com/zenodo/zenodo-rdm/issues/1509) is fixed.
+<%- end -%>
 <%- end -%>
 - Run `bundle exec rake checks` once to confirm your tools are complete: a step that stops on a
   missing command names it ([Prerequisites](#prerequisites) lists them; `nix develop` has them
@@ -152,32 +193,50 @@ bundle exec rake "bump[minor]"      # or major, or patch
 bundle exec rake release
 ```
 
-`rake bump` refuses a release with nothing in it -- the commits since the last tag must hold a
-change a user meets (`feat`, `fix`, `perf`, `build`...): `chore`, `ci` and `style` alone make
-none. It sets the version in `lib/<%= path %>/version.rb` (the first release keeps the version
-declared, whatever the level), updates the lock, writes the changelog (git-cliff) and commits.
+`rake bump` refuses a release with nothing in it: no commit since the last tag, merges and fixups
+aside, which the changelog leaves out. It refuses a shallow clone, a clone missing the tags
+(`git fetch --tags`), a version bumped but not yet released, and one already tagged. It sets the
+version in `lib/<%= path %>/version.rb` (the first release keeps the version declared, whatever the
+level), updates the lock, writes the changelog (git-cliff) and commits.
+<%- if citation -%>
+It sets `CITATION.cff`'s version and date-released too: a citation names the release.
+<%- end -%>
 `rake release`, Bundler's own, builds the gem, tags `v<version>` and pushes the branch and the
-tag; it pushes no gem. The tag runs `release.yml`: the checks and the build, the push to RubyGems
-by Trusted Publishing, then the GitHub release of the same gem, its notes the changelog's new
-section.
+tag; it pushes no gem. The tag runs `release.yml`: the Ruby checks (`rake`), then the build
+(`gem build`, no bundle loaded) and its Sigstore attestation, the push to RubyGems by Trusted
+Publishing, which shows the gem's provenance, then the GitHub release of the same gem, its notes
+the changelog's new section.
 <%- if exe -%>
 Beside `release.yml`, waiting for no RubyGems push, `image.yml` publishes the command's OCI image
 to GHCR (`nix build .#image` builds it here).
 <%- end -%>
 
-`rake release` pushes to `main` directly: with "Require a pull request before merging" on, the
-maintainer cutting it needs the rule's bypass. A refused push leaves the release commit and
-removes the tag (Bundler's doing): run `rake release` again once allowed.
+Should a run fail, re-run its failed jobs, not all of them: those keep the build's gem and
+digests, and RubyGems refuses a version pushed twice. If the gem reached RubyGems but its job
+failed anyway, the release job cannot run: make the GitHub release as it would, from the tag, with
+`--latest=false` unless it is the highest release and `--prerelease` for a pre-release:
+
+```sh
+git checkout vVERSION
+gem fetch <%= name %> --version VERSION
+.github/release-notes.sh CHANGELOG.md VERSION > notes.md
+gh release create vVERSION <%= name %>-VERSION.gem --verify-tag --title vVERSION --notes-file notes.md
+```
+
+`rake release` pushes to `main` directly, and a `v*` tag: with "Require a pull request before
+merging" on, the maintainer cutting it needs the rule's bypass, and the tag ruleset's leave to
+create the tag. A refused push leaves the release commit and removes the tag (Bundler's doing): run
+`rake release` again once allowed. An interrupted push (Ctrl-C) can keep the tag, and a second
+`rake release` then pushes nothing: delete it first (`git tag -d v<version>`).
 
 ## Updating the tools
 
-Dependabot moves the gems (`Gemfile.lock`) and the actions weekly, and the flake's inputs
-monthly; `dependabot-automerge.yml` merges the minor and patch bumps once the checks pass.
+Dependabot moves the gems (`Gemfile.lock`) and the actions weekly, and the flake's inputs monthly;
+`dependabot-automerge.yml` merges the minor and patch bumps once the checks pass. An advisory with
+no fixed version yet fails `security.yml` on every pull request until you weigh it: its ID under
+`ignore:` in `.bundler-audit.yml` (bundler-audit's own file, created then) lets the checks pass.
 dprint's plugins, pinned in `dprint.json`, move by hand: `dprint config update`. A new RuboCop
-brings new cops (`NewCops: enable`), a new Steep new diagnostics: read them before silencing any.
-A bump the new cops fail gets RuboCop's safe corrections as a commit on its branch
-(`rubocop-autocorrect.yml`). GitHub holds the workflows of a commit a workflow's token pushes
-until you approve them (the pull request's "Approve workflows to run"); corrected, the bump then
-merges as any bump. What safe corrections leave is yours to fix, in a pull request of yours too: a
-failed run's summary
-holds the corrections as a patch, to `git apply`.
+brings new cops (`NewCops: enable`), a new Steep new diagnostics: read them before silencing any. A
+bump the new cops fail stays unmerged: its failed run's summary holds RuboCop's safe corrections as
+a patch, to `git apply` on its branch (no workflow pushes code the bumped gems wrote); what they
+leave is yours to fix.

data/template/Gemfile

@@ -2,23 +2,26 @@
 
 source "https://rubygems.org"
 
-# The gem's own dependencies are its gemspec's.
 gemspec
 
-# The development tools, unconstrained: Gemfile.lock pins them and Dependabot moves the lock. No
-# group needed: the built gem holds neither this file nor the lock, its dependencies the
-# gemspec's alone.
 gem "bundler-audit"
 gem "irb"
+gem "rake"
+
 gem "minitest"
+gem "mutineer"
 gem "pbt"
-gem "rake"
+gem "simplecov"
+
 gem "rubocop"
 gem "rubocop-minitest"
 gem "rubocop-packaging"
 gem "rubocop-performance"
 gem "rubocop-rake"
-gem "rubydex"
-gem "simplecov"
+gem "rubydex" # for rubocop UseProjectIndex
+
+gem "yard"
+gem "yard-lint"
+
 gem "steep"
 gem "typeprof"

data/template/README.md.erb

@@ -1,6 +1,6 @@
 # <%= name %>
 
-<%= summary %>
+<%= markdown(summary) %>
 
 ## Requirements
 
@@ -17,9 +17,10 @@ bundle add <%= name %>
 ```
 <%- if exe -%>
 
-With Nix, `nix run github:<%= github %>/<%= name %>`. As an OCI image, for Linux on amd64 and arm64:
+With Nix, or as an OCI image for Linux on amd64 and arm64:
 
 ```sh
+nix run github:<%= github %>/<%= name %> -- --version
 docker run --rm ghcr.io/<%= github.downcase %>/<%= name %> --version
 ```
 <%- end -%>
@@ -42,18 +43,17 @@ require "<%= path %>"
 
 ## Development
 
-`bin/setup` installs the gems at `Gemfile.lock`'s versions (its first run writes the lock); then
-`bundle exec rake` runs the Ruby checks (RuboCop, Steep and the tests with their coverage gate)
-and `bundle exec rake checks` everything CI runs:
+`bin/setup` installs the gems at `Gemfile.lock`'s versions. `bundle exec rake` runs the Ruby checks
+(RuboCop, Steep, the tests and their coverage gate, yard-lint); `bundle exec rake checks` runs all
+of CI's, the links too, mutating the changed lines alone:
 
 ```sh
 bin/setup
 bundle exec rake checks
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for the tools those checks need, how a release is cut and,
-in a project just generated, its [first steps](CONTRIBUTING.md#first-steps); and
-[AGENTS.md](AGENTS.md) for the lint and type policy.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the tools those checks need and how a release is cut,
+and [AGENTS.md](AGENTS.md) for the rules a change follows: lint and types, comments, commits.
 
 ## License
 <%- if license == "dual" -%>
@@ -61,8 +61,8 @@ in a project just generated, its [first steps](CONTRIBUTING.md#first-steps); and
 Licensed under either of
 
 - Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-  <http://www.apache.org/licenses/LICENSE-2.0>)
-- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
+  <https://www.apache.org/licenses/LICENSE-2.0>)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or <https://opensource.org/license/MIT>)
 
 at your option.
 
@@ -74,9 +74,9 @@ any additional terms or conditions.
 <%- elsif license == "mit" -%>
 
 Licensed under the MIT license ([LICENSE-MIT](LICENSE-MIT) or
-<http://opensource.org/licenses/MIT>).
+<https://opensource.org/license/MIT>).
 <%- else -%>
 
 Licensed under the Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
-<http://www.apache.org/licenses/LICENSE-2.0>).
+<https://www.apache.org/licenses/LICENSE-2.0>).
 <%- end -%>

data/template/Rakefile

@@ -1,30 +1,123 @@
 # frozen_string_literal: true
 
-# `rake` runs the Ruby checks, as ruby-ci.yml does; `rake checks` runs everything CI runs.
+# `rake` runs the Ruby checks, as ruby-ci.yml does; `rake checks` runs CI's checks, the links too
+# (links.yml's, monthly), but mutates the changed lines alone (ruby-ci.yml: every line).
 # `rake -T` lists the tasks.
 
 require "bundler/audit/task"
 require "bundler/gem_tasks"
+require "csv"
 require "json"
 require "minitest/test_task"
 require "rubocop/rake_task"
 require "steep/rake_task"
+require "yard"
 
-Minitest::TestTask.create
+# Coverage, `rake test`'s alone: started in the tests' process before they load lib/ (.simplecov);
+# then the helper, whatever order the test files load in (shuffled): one loaded before it would only
+# print its parse-time warnings
+TEST_TASK = Minitest::TestTask.create do
+  self.test_prelude = %(require "simplecov"; SimpleCov.start; require "test_helper")
+end
 RuboCop::RakeTask.new
 Steep::RakeTask.new
 Bundler::Audit::Task.new
 
-task default: %i[rubocop steep test]
+# `rake yard`: lib/'s documentation, in doc/. Not sig/'s: YARD's RBS reader refuses a signature
+# over several lines.
+YARD::Rake::YardocTask.new { it.files = ["lib/**/*.rb"] }
+
+task default: %i[rubocop steep steep:typed test yard_lint]
+
+# A command's standard output, as UTF-8 whatever the locale (git-cliff's commits, their authors' names);
+# its failure fails the task, as `sh`'s does.
+def output(*command)
+  IO.popen(command, external_encoding: Encoding::UTF_8, &:read).tap do
+    raise "#{command.join(" ")} failed" unless Process.last_status.success?
+  end
+end
 
-# TypeProf infers; Steep, against sig/, is the gate. TypeProf reads Ruby's core signatures alone,
-# not the standard library's.
-desc "Print the signatures TypeProf infers from lib/, to start sig/ from, and what it finds amiss"
+# The files git tracks, those still on disk
+def tracked = output("git", "ls-files", "-z").split("\0").select { File.file?(it) }
+
+# git's shell scripts, by name or shebang (shfmt --find)
+def scripts = output("shfmt", "--find", *tracked).lines(chomp: true)
+
+# A call is untyped where its receiver is: steep check passes it, and a steep:ignore leaves it so.
+# steep stats counts them, exiting 0 whatever it counts; a file it cannot type (status error, as a
+# syntax error, which strict steep check reports as information) it counts as none.
+desc "Check that Steep types each call of lib/. steep stats counts the untyped calls"
+task "steep:typed" do
+  stats = CSV.parse(output("steep", "stats", "--format=csv"), headers: true)
+  failed = stats.filter_map do |row|
+    next "#{row["File"]}: not typed (#{row["Status"]})" unless row["Status"] == "success"
+
+    "#{row["File"]}: #{row["Untyped calls"]} untyped" unless row["Untyped calls"] == "0"
+  end
+  abort "error: calls Steep does not type:\n#{failed.join("\n")}" unless failed.empty?
+end
+
+# Steep, against sig/, is the gate. TypeProf reads Ruby's core signatures alone, not the standard
+# library's.
+desc "Print the signatures TypeProf infers. It reads lib/, to start sig/ from, and prints what it finds amiss"
 task :typeprof do
   sh "typeprof", "--show-errors", "lib"
 end
 
-desc "Update the advisory database, then check Gemfile.lock against it (bundler-audit)"
+# yard graph draws what yardoc records (.yardoc): lib/'s, quietly, so the graph alone is printed, and
+# its private methods too (no .yardopts, whose query keeps the public API)
+desc "Print lib/'s classes and modules as a graph. yard graph writes it for Graphviz's `dot`"
+task :graph do
+  sh "yard", "doc", "-n", "-q", "--no-stats", "--no-yardopts", "lib/**/*.rb"
+  sh "yard", "graph", "--protected", "--private", "--full", "--dependencies"
+end
+
+# Every test file `rake test` runs (its globs) but test_helper.rb, which every test requires and holds
+# none: mutineer pairs lib/a/b.rb with one test file by its path (test/a/test_b.rb), and a test may
+# reach any file.
+def mutate(*options)
+  tests = FileList[*TEST_TASK.test_globs].exclude("test/test_helper.rb").uniq.flat_map { ["--test", it] }
+  sh "mutineer", "run", *options, *FileList["lib/**/*.rb"], *tests
+end
+
+# An ignore whose mutant is gone (its method changed or moved) hides nothing and goes stale: migrate
+# --dry-run names each and fails, writing nothing; it counts an ignored copy mutineer drops as used.
+desc "Check that each ignore of .mutineer.yml names a mutant of lib/. mutineer migrate --dry-run"
+task "mutation:ignores" do
+  sh "mutineer", "migrate", "--dry-run", *FileList["lib/**/*.rb"]
+end
+
+desc "Mutate lib/ against the tests. A change none catches fails it (mutineer, .mutineer.yml)"
+task(mutation: "mutation:ignores") { mutate }
+
+# The commit the branch left origin/main at; nil where there is no origin/main (a gem never pushed)
+def merge_base
+  base = IO.popen(%w[git merge-base HEAD origin/main], err: File::NULL, &:read).chomp
+  base unless base.empty?
+end
+
+# The lines changed since the merge base, uncommitted ones too, and every line of a file git does
+# not track (a new one before `git add`), unless git ignores it; every line where there is none
+desc "Mutate lib/'s lines changed since origin/main. `rake mutation` mutates all of them"
+task "mutation:changed" => "mutation:ignores" do
+  base = merge_base
+  mutate(*(["--since", base, "--allow-empty"] if base))
+end
+
+# The files changed since the merge base, uncommitted and untracked ones too (`--changed`); every
+# file where there is none
+desc "Run RuboCop on the files changed since origin/main. `rake rubocop` checks them all"
+task "rubocop:changed" do
+  base = merge_base
+  sh "rubocop", *("--changed=#{base}" if base)
+end
+
+desc "Lint lib/'s YARD documentation with yard-lint. Its rules: .yard-lint.yml"
+task :yard_lint do
+  sh "yard-lint", "lib", "--stats"
+end
+
+desc "Update the advisories, check Gemfile.lock. bundler-audit fetches its database, then checks the lock"
 task audit: %w[bundle:audit:update bundle:audit:check]
 
 desc "Check the Markdown and TOML format (dprint)"
@@ -32,45 +125,43 @@ task :dprint do
   sh "dprint", "check"
 end
 
-desc "Check that every commit is a Conventional Commit (cocogitto)"
+desc "Check every commit message with cocogitto. Each must be a Conventional Commit"
 task :cog do
   sh "cog", "check"
 end
 
-# A command's standard output; its failure fails the task, as `sh`'s does.
-def output(*command)
-  IO.popen(command, &:read).tap { raise "#{command.join(" ")} failed" unless Process.last_status.success? }
-end
-
-desc "Lint and check the format of the shell scripts git tracks (shellcheck, shfmt)"
+desc "Lint and format-check the shell scripts. It checks those git tracks, with shellcheck and shfmt"
 task :shell do
-  tracked = output("git", "ls-files", "-z").split("\0").select { File.file?(it) }
-  scripts = output("shfmt", "--find", *tracked).lines(chomp: true)
-  sh "shellcheck", *scripts
-  sh "shfmt", "--diff", *scripts
+  files = scripts
+  sh "shellcheck", *files
+  sh "shfmt", "--diff", *files
 end
 
-desc "Lint the workflows and audit their security (actionlint, zizmor)"
+desc "Lint the workflows, audit their security. It runs actionlint and zizmor"
 task :workflows do
   sh "actionlint"
   sh "zizmor", "--offline", "--quiet", "--strict-collection", "."
 end
 
-desc "Run the flake's checks: the Nix format, the shell, the workflows, the package (git's files alone)"
+desc "Run the flake's checks. They check the Nix format, the shell, the workflows and the package (git's files)"
 task :nix do
   sh "nix", "flake", "check"
 end
 
-desc "Run every check CI runs"
-task checks: %i[default audit dprint cog shell workflows nix]
+desc "Run CI's checks, mutating the changed lines. It checks the links too; CI mutates every line"
+task checks: %i[default audit dprint cog shell workflows links mutation:changed nix]
 
-desc "Format the Ruby, the Markdown and TOML, and the Nix (modifies files)"
-task format: "rubocop:autocorrect" do
+# RuboCop last: it fails on an offense it cannot correct, after the others have formatted
+desc "Format the Markdown, TOML, Nix, shell and Ruby files. It rewrites them in place"
+task :format do
   sh "dprint", "fmt"
   sh "nix", "fmt"
+  sh "shfmt", "--write", *scripts
+  Rake::Task["rubocop:autocorrect"].invoke
 end
 
-desc "Use .githooks/: the quick checks before a commit, Conventional Commits for every message"
+desc "Use .githooks/ for git's hooks. They run the quick checks before a commit, and check that every " \
+     "message is a Conventional Commit"
 task :hooks do
   sh "git", "config", "core.hooksPath", ".githooks"
 end
@@ -80,24 +171,67 @@ gemspec = Bundler::GemHelper.gemspec
 repository = gemspec.metadata.fetch("source_code_uri").delete_prefix("https://github.com/")
 cliff = ["git-cliff", "--offline", "--github-repo", repository]
 
+# Online, a link that passed cached a day (.lycheecache); a refused connection or a 429 retried at
+# least 10 s apart, so a brief outage is waited out. Not the tests' links, made up; nor GitHub's
+# bare address, read off those the code builds; nor the gem's own pages, missing until it is pushed
+# and published.
+desc "Check the links in git's files with lychee. Not the tests', whose links are made up"
+task :links do
+  files = tracked.grep_v(%r{\Atest/})
+  own = [gemspec.homepage, "https://rubygems.org/gems/#{gemspec.name}", "https://rubydoc.info/gems/#{gemspec.name}"]
+  skip = ["^#{Regexp.escape("https://github.com/")}$", "^(#{own.map { Regexp.escape(it) }.join("|")})($|/)"]
+  sh "lychee", "--no-progress", "--cache", "--retry-wait-time", "10", *skip.flat_map { ["--exclude", it] }, *files
+end
+
 desc "Preview the changelog's next section"
 task :changelog do
   sh(*cliff, "--unreleased")
 end
 
+# The release tags, refused where they do not tell the releases: a shallow clone, or a clone without
+# them that has a CHANGELOG.md
+def release_tags
+  if output("git", "rev-parse", "--is-shallow-repository") == "true\n"
+    abort "error: a shallow clone, which the changelog cannot be written from: git fetch --unshallow"
+  end
+  tags = output("git", "tag", "--list", "v[0-9]*").lines(chomp: true)
+  return tags unless tags.empty? && File.exist?("CHANGELOG.md")
+
+  abort "error: a CHANGELOG.md but no v* tag: git fetch --tags, or release the version bumped first"
+end
+
 # The version to release: the declared one at the first release (no tag yet), else +level+'s
-# number bumped (0 major, 1 minor, 2 patch), those after it zeroed.
+# number bumped (0 major, 1 minor, 2 patch), those after it zeroed. The current version must be
+# tagged: else it was bumped and never released.
 def next_version(current, level)
   abort "error: #{current} is not MAJOR.MINOR.PATCH" unless current.match?(/\A\d+\.\d+\.\d+\z/)
-  return current if output("git", "tag", "--list", "v[0-9]*").empty?
+  tags = release_tags
+  return current if tags.empty?
+
+  abort "error: v#{current} is not tagged: git fetch --tags, or release it first" unless tags.include?("v#{current}")
 
   parts = current.split(".").map(&:to_i)
   parts[level] += 1
   parts.fill(0, level + 1).join(".")
 end
 
-# The release commit: the version, the lock, the changelog.
-desc "Bump the version (major, minor or patch), write the changelog and commit"
+# CITATION.cff, where the gem has one (bundle veragem --citation): its text with the release's version
+# and date, or nil; read as UTF-8, as written, whatever the locale. The date is UTC's, as the
+# changelog's (git-cliff's `date` filter).
+def cited(version)
+  return unless File.exist?("CITATION.cff")
+
+  released = { "version" => version, "date-released" => Time.now.utc.strftime("%F") }
+  released.reduce(File.read("CITATION.cff", encoding: Encoding::UTF_8)) do |cff, (key, value)|
+    abort "error: CITATION.cff has no #{key}: line" unless cff.match?(/^#{key}: /)
+
+    cff.sub(/^#{key}: [^\r\n]*/, %(#{key}: "#{value}"))
+  end
+end
+
+# The release commit: the version, the lock, the changelog, and CITATION.cff's version and date.
+desc "Bump the version, write the changelog, commit. The level is major, minor or patch; a first release " \
+     "keeps the declared version"
 task :bump, [:level] => "release:guard_clean" do |_, args|
   level = %w[major minor patch].index(args[:level]) or abort 'usage: rake "bump[major|minor|patch]"'
   current = gemspec.version.to_s
@@ -109,12 +243,14 @@ task :bump, [:level] => "release:guard_clean" do |_, args|
 
   file = "lib/#{gemspec.name.tr("-", "/")}/version.rb"
   abort "error: #{file} declares no \"#{current}\"" unless File.read(file).include?(%("#{current}"))
+  citation = cited(version)
   first = !File.exist?("CHANGELOG.md")
   begin
     File.write(file, File.read(file).sub(%("#{current}"), %("#{version}")))
+    File.write("CITATION.cff", citation) if citation
     sh "bundle", "lock"
     sh(*cliff, "--tag", "v#{version}", "--output", "CHANGELOG.md")
-    sh "git", "add", file, "Gemfile.lock", "CHANGELOG.md"
+    sh "git", "add", file, "Gemfile.lock", "CHANGELOG.md", *("CITATION.cff" if citation)
     sh "git", "commit", "--message", "chore(release): v#{version}"
   rescue StandardError, Interrupt
     # The tracked files were committed (release:guard_clean): put back what this changed.
@@ -128,7 +264,7 @@ end
 # The gem is published by release.yml, on the tag, through RubyGems' Trusted Publishing:
 # `rake release` builds it, tags v<version> and pushes the branch and the tag, and pushes no gem.
 Rake::Task["release"].clear_comments
-Rake::Task["release"].add_description("Tag v#{gemspec.version}, push the branch and the tag: release.yml publishes it")
+Rake::Task["release"].add_description("Tag v#{gemspec.version}, push the branch and the tag. release.yml publishes it")
 Rake::Task["release:rubygem_push"].clear_actions
 desc "Push no gem: release.yml publishes the tag"
 task "release:rubygem_push" do