veragem 0.1.0 → 0.2.0

data/template/.github/workflows/release.yml

@@ -1,13 +1,17 @@
-# A release tag, v<version> (`rake bump`, then `rake release`), publishes the gem: checked and built
-# once, pushed to RubyGems through Trusted Publishing (no API key stored), then its GitHub release
-# of the same file, its notes the release's section of CHANGELOG.md (release-notes.sh). Trusted
-# Publishing needs, once, a (pending) trusted publisher on rubygems.org naming this repository,
-# this workflow (release.yml) and the `release` environment.
+# A release tag, v<version> (`rake bump`, then `rake release`), publishes the gem: checked, then
+# built and signed once, pushed to RubyGems through Trusted Publishing (no API key stored) with its
+# Sigstore attestation, then its GitHub release of the same file, its notes the release's section of
+# CHANGELOG.md (release-notes.sh). Trusted Publishing needs, once, a (pending) trusted publisher on
+# rubygems.org naming this repository, this workflow (release.yml) and the `release` environment.
 #
 # Least privilege, as RubyGems' Trusted Publishing advises, after PyPI's security model: the
-# build, which runs the checks and the gemspec, writes nothing but its artifacts and mints no key;
-# only the RubyGems job can mint one, with nothing checked out and no Gemfile or Rakefile loaded;
-# only the release job can write the repository.
+# checks, which load the bundle's gems, write nothing; the build, apart from them, loads no bundle,
+# so no tool's gem touches the file published; its path and digest, job outputs no later job can
+# rewrite, name the one file signed, pushed and released, checked first; the signing job, which runs
+# Sigstore's action, signs as this workflow outside the environment the publisher names, so it
+# mints no key; only the RubyGems job can mint one, with nothing checked out, no Gemfile or Rakefile
+# loaded and no action but the artifacts' download, setup-ruby's and the credentials'; only the
+# release job can write the repository.
 name: Release
 
 on:
@@ -17,8 +21,8 @@ on:
 permissions: {}
 
 jobs:
-  build:
-    name: Check and build
+  check:
+    name: Check
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -35,25 +39,60 @@ jobs:
 
       - name: The gems, from Gemfile.lock
         # installed afresh, not restored from bundler-cache: a cache any run on main can write is
-        # never an input to the gem published
+        # never an input to a release
         env:
           BUNDLE_FROZEN: "true"
         run: bundle install
 
-      - name: RuboCop, Steep, the tests
+      - name: RuboCop, Steep, the tests, yard-lint
         run: bundle exec rake
 
+  build:
+    name: Build
+    needs: check
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    outputs:
+      gem: ${{ steps.build.outputs.gem }}
+      sha256: ${{ steps.build.outputs.sha256 }}
+      notes: ${{ steps.build.outputs.notes }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          ruby-version: "4.0"
+          bundler: none
+
       - name: Build the gem, and its notes
+        id: build
+        # RubyGems' own build, the gemspec alone: the same files as Bundler's `rake build`
         run: |
           set -euo pipefail
-          version="$(ruby -e 'puts Gem::Specification.load(Dir["*.gemspec"].first).version')"
+          gemspec="$(ruby -e 'print Dir["*.gemspec"].first')"
+          version="$(ruby -e 'print Gem::Specification.load(ARGV[0]).version' "$gemspec")"
           if [[ $GITHUB_REF_NAME != "v$version" ]]; then
             echo "::error::$GITHUB_REF_NAME, but the gemspec's version is $version" >&2
             exit 1
           fi
-          # into pkg/, as Bundler's gem tasks build it
-          bundle exec rake build
+          mkdir pkg
+          gem="pkg/${gemspec%.gemspec}-$version.gem"
+          gem build "$gemspec" --output "$gem"
           .github/release-notes.sh CHANGELOG.md "$version" > notes.md
+          # assigned first: a failing command substitution inside echo's arguments would not stop
+          # the step
+          sha256="$(sha256sum "$gem")"
+          notes="$(sha256sum notes.md)"
+          {
+            echo "gem=$gem"
+            echo "sha256=$sha256"
+            echo "notes=$notes"
+          } >> "$GITHUB_OUTPUT"
 
       - name: Keep the gem
         uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
@@ -69,9 +108,40 @@ jobs:
           path: notes.md
           if-no-files-found: error
 
+  sign:
+    name: Sign
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Sigstore's certificate: this workflow's identity, which RubyGems checks
+    steps:
+      - name: The build's gem
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: gem
+          path: pkg/
+
+      - name: Sign
+        # Sigstore's action, which writes the bundle beside the gem (<gem>.sigstore.json), and
+        # RubyGems takes any v0.3 bundle that verifies (rubygems.org's Pusher). The code that can
+        # sign as this workflow: the action pinned and moved by Dependabot, its sigstore-python with
+        # it (hash-pinned requirements), but not the uv it installs first, uv's newest
+        # (setup/create-venv.sh). A bad one can fail the push, not change the gem (its digest) nor
+        # add one: the jobs after it take the build's path alone
+        uses: sigstore/gh-action-sigstore-python@790bc6befb9d733738f18d8f895854b453640ec9 # v3.5.0
+        with:
+          inputs: ${{ needs.build.outputs.gem }}
+
+      - name: Keep the attestation
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: attestation
+          path: pkg/*.sigstore.json
+          if-no-files-found: error
+
   rubygems:
     name: RubyGems
-    needs: build
+    needs: [build, sign]
     runs-on: ubuntu-latest
     environment:
       name: release
@@ -84,19 +154,41 @@ jobs:
           name: gem
           path: pkg/
 
+      - name: Its attestation
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: attestation
+          path: pkg/
+
+      - name: The build's gem, unchanged
+        # its artifact replaceable by a later job of the run (the signing job's code): its digest is
+        # the build's output
+        env:
+          SHA256: ${{ needs.build.outputs.sha256 }}
+        run: sha256sum --check --strict <<< "$SHA256"
+
+      - name: Set up Ruby
+        # the runner image's RubyGems predates `gem push --attestation`
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          ruby-version: "4.0"
+          bundler: none
+
       - name: Trusted Publishing's API key
         uses: rubygems/configure-rubygems-credentials@dc5a8d8553e6ee01fc26761a49e99e733d17954a # v2.1.0
 
       - name: Push
-        # the runner image's RubyGems: no other action in the one job that can mint a key
-        run: gem push pkg/*.gem
+        # RubyGems verifies the attestation, and shows the gem's provenance
+        env:
+          GEM: ${{ needs.build.outputs.gem }}
+        run: gem push "$GEM" --attestation "$GEM.sigstore.json"
 
   release:
     name: GitHub release
-    needs: rubygems
+    needs: [build, rubygems]
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: write # the release, and its tags read
     steps:
       - name: The build's gem
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
@@ -109,9 +201,30 @@ jobs:
         with:
           name: notes
 
+      - name: The build's gem and notes, unchanged
+        # as the RubyGems job checks the gem
+        env:
+          SHA256: ${{ needs.build.outputs.sha256 }}
+          NOTES: ${{ needs.build.outputs.notes }}
+        run: printf '%s\n' "$SHA256" "$NOTES" | sha256sum --check --strict
+
       - name: Release
         env:
           GH_TOKEN: ${{ github.token }}
+          GEM: ${{ needs.build.outputs.gem }}
         run: |
-          gh release create "$GITHUB_REF_NAME" pkg/*.gem --repo "$GITHUB_REPOSITORY" --verify-tag \
-            --title "$GITHUB_REF_NAME" --notes-file notes.md
+          set -euo pipefail
+          # GitHub's latest release is the highest final one, as image.yml's `latest` is: by default,
+          # GitHub makes each new release the latest, a patch to an older line too
+          highest="$(gh api "repos/$GITHUB_REPOSITORY/git/matching-refs/tags/v" --paginate \
+            --jq '.[].ref | ltrimstr("refs/tags/v")' \
+            | { grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' || true; } | sort -V | tail -n 1)"
+          version="${GITHUB_REF_NAME#v}"
+          latest=false
+          if [[ $version == "$highest" ]]; then latest=true; fi
+          # a pre-release as RubyGems reads one: a letter in its version (Gem::Version#prerelease?)
+          prerelease=false
+          if [[ $version =~ [a-zA-Z] ]]; then prerelease=true; fi
+          gh release create "$GITHUB_REF_NAME" "$GEM" --repo "$GITHUB_REPOSITORY" --verify-tag \
+            --title "$GITHUB_REF_NAME" --notes-file notes.md --latest="$latest" \
+            --prerelease="$prerelease"

data/template/.github/workflows/ruby-ci.yml

@@ -1,13 +1,13 @@
-# The Ruby checks, `bundle exec rake` (RuboCop, Steep, the tests with their coverage gate), on each
-# Ruby the matrix lists, the gems installed from Gemfile.lock; then TypeProf's verdict, advisory.
+# The Ruby checks, `bundle exec rake` (RuboCop, Steep, the tests with their coverage gate,
+# yard-lint), on each Ruby the matrix lists, on Linux, macOS and Windows, the gems installed from
+# Gemfile.lock; then TypeProf's verdict, advisory. Beside them, the mutation test of every line: a
+# change to the tests alone weakens them, and has no changed line to mutate.
 # nix.yml runs the flake's checks: the Nix format, the shell, the workflows, the package.
 name: Ruby CI
 
 on:
   push:
     branches: [main]
-  # every pull request, whatever it touches: a path-filtered workflow never reports, and a
-  # required check that never reports blocks the merge
   pull_request:
   workflow_dispatch:
 
@@ -22,13 +22,18 @@ permissions:
 
 jobs:
   checks:
-    name: Checks (Ruby ${{ matrix.ruby }})
-    runs-on: ubuntu-latest
+    name: Checks (Ruby ${{ matrix.ruby }}, ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
         # the gemspec's required_ruby_version, and each newer Ruby once released
         ruby: ["4.0"]
+    # Windows' default is PowerShell: the scripts below are bash, Git for Windows' there
+    defaults:
+      run:
+        shell: bash
     steps:
       - name: Checkout
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -42,15 +47,14 @@ jobs:
           ruby-version: ${{ matrix.ruby }}
           bundler-cache: true
 
-      - name: RuboCop, Steep, the tests
-        # RuboCop's offences as annotations too, on a pull request's lines (its github formatter)
+      - name: RuboCop, Steep, the tests, yard-lint
         env:
           RUBOCOP_OPTS: --format progress --format github
         run: bundle exec rake
 
       - name: RuboCop's safe corrections, as a patch
         # a failed run's: what `rake rubocop:autocorrect` changes, in the run's summary, to
-        # `git apply` (a Dependabot bump's, rubocop-autocorrect.yml commits)
+        # `git apply` -- a Dependabot bump's too, which a failed run keeps from auto-merging
         if: failure()
         run: |
           bundle exec rake rubocop:autocorrect || true
@@ -60,3 +64,21 @@ jobs:
 
       - name: TypeProf (advisory)
         run: bundle exec rake typeprof
+
+  mutation:
+    name: Mutation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@7f797815d8adceb1c412e7abefdd1ab4abc47a5f # v1.335.0
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+
+      - name: mutineer, every line
+        run: bundle exec rake mutation

data/template/.github/workflows/security.yml

@@ -1,23 +1,29 @@
-# bundler-audit: Gemfile.lock against the Ruby Advisory Database -- daily, on demand, and when the
-# lock changes (`rake audit`). A finding fails the run, notified to the workflow's creator (or
-# whoever last changed its cron: docs.github.com, "Notifications for workflow runs"). GitHub
-# disables a public repository's schedule after 60 days without activity ("Events that trigger
-# workflows"): Dependabot alerts, the repository's setting, watch the lock without one.
+# bundler-audit: Gemfile.lock against the Ruby Advisory Database -- daily, on demand, on every pull
+# request and when main's lock changes (`rake audit`). A finding fails the run, notified to the
+# workflow's creator (or whoever last changed its cron: docs.github.com, "Notifications for
+# workflow runs"). GitHub disables a public repository's schedule after 60 days without activity
+# ("Events that trigger workflows"): Dependabot alerts, the repository's setting, watch the lock
+# without one.
 name: Security
 
 on:
   schedule:
-    - cron: "0 0 * * *" # daily, midnight UTC
+    - cron: "23 3 * * *" # daily, 03:23 UTC: off the hour and midnight, when GitHub delays runs
   workflow_dispatch:
   push:
     branches: [main]
     paths:
       - "Gemfile.lock"
       - ".github/workflows/security.yml"
+  # every pull request, whatever it touches: a check that always reports can be required, and
+  # so gate a bump's auto-merge on the advisories
   pull_request:
-    paths:
-      - "Gemfile.lock"
-      - ".github/workflows/security.yml"
+
+# a pull request's newest run cancels its older ones; any other run, a group of its own: every
+# commit on main checked (in a shared group, a pending run gives way to the newest: the default)
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
 
 permissions:
   contents: read

data/template/.github/workflows/style-check-cocogitto.yml

@@ -1,9 +1,8 @@
 name: Conventional Commits Check
 
-# On a push, the whole history rather than `--from-latest-tag`: with no tag
-# yet, cog stops "unable to get any tag" -- every new project's first push.
-# A pull request's title too: a squash merge of two or more commits makes the
-# title the commit, and so a changelog entry -- checked again when edited.
+# On a push, the whole history, not `--from-latest-tag`: with no tag yet (a new project's first
+# push), cog stops "unable to get any tag". A pull request's title too, checked again when edited:
+# a squash merge of two or more commits makes the title the commit, and so a changelog entry.
 
 on:
   push:

data/template/.github/workflows/style-check-dprint.yml

@@ -1,4 +1,4 @@
-# The action installs dprint's latest release, attested; the formatting is
+# dprint as flake.lock's nixpkgs has it (the dev shell's version), fetched alone; the formatting is
 # the plugins', pinned in dprint.json.
 name: Dprint Formatting Checks
 
@@ -6,17 +6,16 @@ on:
   push:
     branches: [main]
     paths:
-      # dprint.json's plugins' extensions, markdown and toml, no more: one
-      # no plugin handles (yaml, json, Dockerfile) only schedules runs that
-      # check nothing. Add a plugin there and its extensions here together,
-      # each its own entry: path filters have no brace expansion {a,b}.
+      # dprint.json's plugins' extensions (markdown, toml), no more: one no plugin handles (yaml,
+      # json, Dockerfile) only schedules runs that check nothing. Add a plugin there and its
+      # extensions here together, each its own entry: path filters have no brace expansion {a,b}.
       - "**/*.md"
       - "**/*.markdown"
       - "**/*.toml"
       - ".github/workflows/style-check-dprint.yml"
       - "dprint.json"
-  # every pull request, whatever it touches: a path-filtered workflow never
-  # reports, and a required check that never reports blocks the merge
+  # every pull request, whatever it touches: a path-filtered workflow does not report on one
+  # outside its paths, and a required check that does not report blocks the merge
   pull_request:
 
 # a pull request's newest run cancels its older ones; any other run, a group of its own: every
@@ -38,7 +37,8 @@ jobs:
         with:
           persist-credentials: false
 
+      - name: Install Nix
+        uses: cachix/install-nix-action@75c75c31ebece974e48ebc36b4ad125bd97bd97b # v31.11.3
+
       - name: Dprint format check
-        uses: dprint/check@7dc032d8874778fc024f6f9b4a7e6d896782c330 # v2.5
-        with:
-          config-path: dprint.json
+        run: nix run --inputs-from . nixpkgs#dprint -- check

data/template/.gitignore

@@ -10,3 +10,8 @@
 # Nix's build links, direnv's cache
 /result*
 /.direnv
+/.ruby-lsp/
+# mutineer's coverage map (`rake mutation`), lychee's cache (`rake links`)
+/.mutineer/
+/.lycheecache
+/.yardoc/

data/template/.mutineer.yml

@@ -0,0 +1,28 @@
+# mutineer (`rake mutation`): every operator, not its default five; a minute a mutant, as a test that
+# starts a process can take tens of seconds, and a mutant over the limit counts as neither caught
+# nor survived. A surviving mutant fails the run: the score, of the mutants the tests reach and
+# not ignored, is 100%.
+operators:
+  - arithmetic
+  - comparison
+  - boolean_connector
+  - boolean_literal
+  - statement_removal
+  - return_nil
+  - literal_mutation
+  - condition_negation
+  - string_literal
+  - regex
+  - collection_method
+  - safe_navigation
+  - range
+  - negation_removal
+  - chain_link
+  - call_to_receiver
+  - operand_removal
+  - array_literal
+  - condition_true
+  - condition_false
+  - operator_assignment
+timeout: 60
+threshold: 100

data/template/.rubocop.yml

@@ -1,6 +1,10 @@
-# RuboCop's defaults, each new cop on as it ships, and its extensions for the tests, packaging (the
-# gem as distributions build it), performance and the Rakefile. The Ruby version is the gemspec's
-# required_ruby_version.
+AllCops:
+  Exclude:
+    - "result*/**/*" # `nix build`'s links: the gem installed, which the project index would take for a second copy
+  NewCops: enable # pending cops on now, not only at the next major release
+  ProjectIndexIncludesGems: true # the bundle's gems' sources indexed too: under `bundle exec rubocop` alone
+  UseProjectIndex: true # the rubydex gem indexes the project: cops see across files (a method defined twice)
+
 plugins:
   - rubocop-minitest
   - rubocop-packaging
@@ -11,14 +15,49 @@ inherit_mode:
   merge:
     - Exclude
 
-AllCops:
-  NewCops: enable
-  # `nix build`'s links: the gem installed, which the project index would take for a second copy
+Gemspec/DependencyVersion:
+  Enabled: true
+
+Layout/ClassStructure:
+  Enabled: true
+  ExpectedOrder:
+    - module_inclusion
+    - constants
+    - public_attribute_macros
+    - public_class_methods
+    - initializer
+    - public_methods
+    - protected_attribute_macros
+    - protected_methods
+    - private_attribute_macros
+    - private_class_methods
+    - private_methods
+  Categories:
+    attribute_macros:
+      - attr_accessor
+      - attr_reader
+      - attr_writer
+    module_inclusion:
+      - include
+      - prepend
+      - extend
+
+Layout/EmptyLineAfterMultilineCondition:
+  Enabled: true
+
+Layout/EndOfLine: # LF, as .gitattributes checks every text file out, Windows' too; `native` wants CRLF there
+  EnforcedStyle: lf
+
+Layout/HeredocArgumentClosingParenthesis:
+  Enabled: true
+
+Layout/LeadingCommentSpace:
+  AllowSteepAnnotation: true # Steep's inline annotations, `#: Type`, which have no space after the `#`
+
+Style/TopLevelMethodDefinition: # a method on Object, everywhere; a script's helpers are its own
+  Enabled: true
   Exclude:
-    - "result*/**/*"
-  # the whole project indexed first (the rubydex gem), so the cops that can see across files do: a
-  # method defined twice in two files, a constant reassigned in another
-  UseProjectIndex: true
+    - Rakefile
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/template/.simplecov.erb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# `rake test`'s coverage, started before the tests load lib/ (the Rakefile): every line, branch and
+# method of lib/, a file the tests never load included (`cover`). But version.rb: the gemspec
+# requires it, as Bundler reads the gemspec before coverage starts -- a constant alone.
+SimpleCov.configure do
+  load_profile "strict"
+  cover "lib/**/*.rb"
+  skip "lib/<%= path %>/version.rb"
+end