veragem 0.1.0 → 0.2.0

data/README.md

@@ -1,28 +1,42 @@
 # veragem
 
-A Bundler plugin that generates a Ruby gem with its toolchain wired up: the Ruby counterpart of
-the [templates](https://github.com/veralvx/templates) repository's Python and Rust templates.
+A Bundler plugin that generates a Ruby 4.0+ gem with its toolchain wired up: Steep types,
+RuboCop, Minitest at 100% coverage with mutation testing, YARD, CI on Linux, macOS and Windows, a
+Nix flake and releases by Trusted Publishing. It is the Ruby counterpart of the
+[templates](https://github.com/veralvx/templates) repository's Python and Rust templates.
 `bundle gem` gives a gemspec, a Rakefile, Minitest and RuboCop; `bundle veragem NAME` gives that
 and the rest:
 
-- **Ruby 4.0** or later, `required_ruby_version` and CI alike.
-- **Types**: Steep checks `lib/` against the signatures in `sig/`, its strictest diagnostics on;
-  TypeProf infers signatures to start them from, and its editor support is configured.
+- **Ruby 4.0** or later, `required_ruby_version` and CI alike, on Linux, macOS and Windows:
+  Gemfile.lock holds Windows' platform (`bin/setup`), `.gitattributes` keeps every text file LF,
+  and the executables' mode is in git's index, which a commit keeps where the file system has none.
+- **Types**: Steep checks `lib/` against the signatures in `sig/`, its `strict` diagnostics on, and
+  that each call is typed (`rake steep:typed`: none on an untyped receiver); TypeProf infers
+  signatures to start them from, and its editor support is configured.
 - **Lint and format**: RuboCop with every new cop, rubocop-minitest, rubocop-packaging,
   rubocop-performance and rubocop-rake; the project is indexed first (rubydex), so the cops that see
   across files do. In CI, offences are annotated on the pull request and a failed run's summary
-  holds the safe corrections as a patch; a Dependabot bump the new cops fail gets them as a commit,
-  then merges as any bump once you approve its runs (`rubocop-autocorrect.yml`, no token to set).
+  holds the safe corrections as a patch, to `git apply`: a Dependabot bump the new cops fail stays
+  unmerged until you apply it, no workflow pushing code the bumped gems wrote.
+- **Documentation**: YARD, every public object of `lib/` documented, held by yard-lint at 100%
+  coverage (`rake yard` writes it to `doc/`).
 - **Tests**: Minitest, a property test with [pbt](https://github.com/ohbarye/pbt), and SimpleCov's
-  `strict` profile: every line, branch and method of `lib/` covered.
-- **Security**: bundler-audit over `Gemfile.lock`, daily in CI; a pull request's new gems and
-  actions reviewed for their licences and advisories (`dependency-review.yml`, advisory, as in the
-  Python and Rust templates); zizmor over the workflows and Dependabot's configuration; Dependabot
-  for the gems, the actions and the flake, a release proposed once a week old.
+  `strict` profile: every line, branch and method of `lib/` covered; a warning from `lib/` or the
+  tests fails them. [mutineer](https://github.com/davidteren/mutineer) mutates `lib/`: one mutant
+  no test catches, or an ignore that names none, fails it. `rake checks` mutates the lines changed
+  since `origin/main`, CI every line (`rake mutation`).
+- **Links**: lychee checks the links of the files git tracks but the tests' (`rake links`), in
+  `rake checks` and monthly (`links.yml`).
+- **Security**: bundler-audit over `Gemfile.lock`, daily and on every pull request; a pull request's
+  new gems reviewed for their licences and advisories, its new actions for their licences
+  (`dependency-review.yml`, not a required check, as in the Python and Rust templates); zizmor over
+  the workflows and Dependabot's configuration; Dependabot for the gems, the actions and the flake,
+  each update proposed once its release is a week old.
 - **Commits and releases**: Conventional Commits (cocogitto, in CI and opt-in git hooks), a
   changelog written by git-cliff at each release, `rake "bump[minor]"` then Bundler's own
-  `rake release`; the tag publishes to RubyGems by Trusted Publishing, no API key stored, and makes
-  the GitHub release.
+  `rake release`; the tag publishes to RubyGems by Trusted Publishing, no API key stored, the gem
+  built apart from the tools' gems and signed (its Sigstore attestation, RubyGems' provenance), and
+  makes the GitHub release.
 - **Nix**: a flake with the development shell (Ruby and every tool the checks run), the gem as a
   package (`nix build`), `nix fmt`, and checks for the Nix, the shell scripts, the workflows and
   the package. With `--exe`, `nix run` runs the command, and its OCI image (`nix build .#image`)
@@ -31,11 +45,11 @@ and the rest:
   `AGENTS.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`), issue and pull request templates.
 
 In the generated gem, `bundle exec rake` runs the Ruby checks, as CI does;
-`bundle exec rake checks` runs everything CI runs.
+`bundle exec rake checks` runs CI's checks, the links too, but mutates the changed lines alone.
 
 ## Install
 
-Ruby 4.0 or later, then:
+Ruby 4.0 or later and git, then:
 
 ```sh
 bundle plugin install veragem
@@ -43,69 +57,146 @@ bundle plugin install veragem
 
 Run outside a project, it installs for your user, and `bundle veragem` then works anywhere. From
 the repository instead: `bundle plugin install veragem --git https://github.com/veralvx/veragem`
-(or `--path` a local checkout).
+(or `--path` a local checkout). This README follows `main`, which can be ahead of the release:
+[CHANGELOG.md](CHANGELOG.md) lists what each release holds, and `--git` installs `main`.
 
 ## Usage
 
 ```sh
-bundle veragem my_gem   # and --author, --github where git config has no user.name, github.user
+bundle veragem my_gem   # with a terminal for input, it asks for what no option gives
 cd my_gem
 bin/setup               # the gems, and Gemfile.lock written
 git add .
 git commit -m "chore: initial commit from veragem"
-bundle exec rake checks # its tools: the generated CONTRIBUTING.md's, or `nix develop`'s
+bundle exec rake checks # the tools the generated CONTRIBUTING.md lists, or `nix develop`'s
 ```
 
-| Option              | Default                             | Goes into                                       |
-| ------------------- | ----------------------------------- | ----------------------------------------------- |
-| `NAME`              | --                                  | the gem, its module, its files: as `bundle gem` |
-| `--exe`             | a library alone                     | a command line: `exe/NAME`, `lib/NAME/cli.rb`   |
-| `--license=LICENSE` | `dual` (MIT OR Apache-2.0)          | `mit`, `apache` or `dual`: the gemspec, LICENSE |
-| `--author=NAME`     | `git config user.name` (required)   | the gemspec, the licence's copyright line       |
-| `--email=EMAIL`     | `git config user.email` (optional)  | the gemspec, the code of conduct                |
-| `--github=USER`     | `git config github.user` (required) | the homepage, the repository's links            |
-| `--summary=TEXT`    | `A Ruby gem.`                       | the gemspec, the README, the module's comment   |
+As `bundle gem` does, veragem makes the git repository and adds the files, and runs no
+`bundle install`: `bin/setup` writes the lock, to commit. The generated `CONTRIBUTING.md` lists
+the first steps: the repository's settings, RubyGems' pending trusted publisher.
+
+### Options
+
+| Option                     | Default                                     | Goes into                                              |
+| -------------------------- | ------------------------------------------- | ------------------------------------------------------ |
+| `NAME`                     | --                                          | the gem, its module, its files: as `bundle gem`        |
+| `--[no-]exe`               | `--no-exe`: a library alone                 | a command line: `exe/NAME`, `lib/PATH/cli.rb`          |
+| `--license=LICENSE`        | `dual` (MIT OR Apache-2.0)                  | `mit`, `apache` or `dual`: the gemspec, LICENSE        |
+| `--author=NAME`            | `git config user.name` (required)           | the gemspec, the licence's copyright line              |
+| `--[no-]email=EMAIL`       | `git config user.email`; `--no-email`: none | the gemspec, the code of conduct                       |
+| `--github=USER`            | `git config github.user` (required)         | the homepage, the repository's links                   |
+| `--summary=TEXT`           | `A Ruby gem.`                               | the gemspec, the README, the module's comment          |
+| `--[no-]citation`          | `--no-citation`                             | `CITATION.cff`: GitHub's "Cite this repository"        |
+| `--family-names=NAMES`     | (required with `--citation`)                | with `--citation`: the author's, `CITATION.cff`        |
+| `--[no-]given-names=NAMES` | optional; `--no-given-names`: none          | with `--citation`: the author's, `CITATION.cff`        |
+| `--[no-]alias=ALIAS`       | optional; `--no-alias`: none                | with `--citation`: the author's handle, `CITATION.cff` |
+| `--orcid=ID`               | optional                                    | with `--citation`: the author's ORCID iD               |
+| `--keywords=LIST`          | optional                                    | with `--citation`: keywords, comma-separated           |
+
+A licence, an option's or an answer's, is taken in any case, abbreviated (`a`) or as its SPDX
+expression (`Apache-2.0`, `MIT OR Apache-2.0` in either order). Without a terminal, when veragem
+refuses a value from git's config, its error names the key and the option or options that replace
+it.
+
+### Questions
+
+With a terminal for input, `bundle veragem` asks for each value no option gives, the name too, once
+the options are checked. A question offers its default unless veragem refuses it, saying why and
+where it is from (`git config user.name`); Enter takes it, an optional one takes `-` for none, and a
+refused answer, or none where there is no default, is asked again, saying why. `-` is no option's
+value, as no answer can give it: `--no-email`, `--no-given-names` and `--no-alias` give none, and an
+`--orcid` or `--keywords` left out does. With other input (CI, a pipe, `< /dev/null` to skip the
+questions) nothing is asked: the defaults apply, and a missing name, author, GitHub user or, with
+`--citation`, family names is refused.
+
+### CITATION.cff
+
+`CITATION.cff` (Citation File Format 1.2.0) is for research software meant to be cited: GitHub
+offers its "Cite this repository", and Zenodo, once the repository is enabled there (the generated
+CONTRIBUTING.md's first steps), archives each release with its values and gives it a DOI. Its
+author is a person, family names required, given names, alias, ORCID iD and keywords optional.
+Asked at a terminal, the family names offer the author's last word, the given names the words before
+the family names, where the author ends with them, and the alias, asked last, the GitHub user. That
+user may be an organization, so it is only offered: without a terminal, there is no alias unless
+`--alias` gives one. The citation's options need `--citation`: given without it, they are refused,
+and at a terminal they make its question take y alone.
+
+It holds what GitHub and Zenodo read, written as Zenodo's import takes it (narrower than CFF), but
+the licences as CFF writes them:
+
+- one licence as its SPDX identifier, and `dual`'s two as a list, CFF's OR: Zenodo's import refuses
+  a list, so it archives no release of a dual-licensed gem until
+  [zenodo/zenodo-rdm#1509](https://github.com/zenodo/zenodo-rdm/issues/1509) is fixed (first
+  reported as [zenodo/zenodo#2515](https://github.com/zenodo/zenodo/issues/2515));
+- an ORCID iD Zenodo's check takes, its check digit and its block ORCID's, written as its URL;
+- names without a comma: Zenodo reads one as the end of the family names (`Smith, Jr.`); an alias
+  may hold one, as Zenodo reads no alias;
+- a name of 3 characters or more, Zenodo's least title;
+- the repository, RubyGems' page as its artifact, and its API documentation on rubydoc.info as
+  its URL (there from the first release); no email (CFF's pattern is stricter than veragem's);
+- its DOIs commented out, the concept DOI and a version's, to uncomment once Zenodo gives them
+  after a release.
+
+`rake bump` sets its version and date at each release, and `nix flake check` validates it against
+CFF's schema (cffconvert): a check of the schema alone, which passes files Zenodo's import refuses.
+
+### The name
 
 The name follows `bundle gem`'s rules, lower-case: `my_gem` is `MyGem` in `lib/my_gem.rb`, `my-gem`
 is `My::Gem` in `lib/my/gem.rb`. Refused before anything is written, a name:
 
-- whose module is already defined, by Ruby, Bundler, Rake or Minitest, or by its top-level library
-  where this Ruby has one (`set`, `option_parser`, `date-holidays`: Date is a class);
-- whose file would shadow a library this Ruby has (`json`: lib/json.rb);
+- whose module is already defined, by Ruby, by what its tools load with its code (Bundler, the
+  Rakefile and its tasks, the console, the tests: `c_s_v`, `j_s_o_n`, `weak_ref`), where installed,
+  or by its top-level library where this Ruby has one (`set`, `option_parser`, `date-holidays`: Date
+  is a class);
+- whose file would shadow a library this Ruby has, in any case, as macOS and Windows ignore it
+  (`ripper`: lib/ripper.rb; `english`: English.rb);
 - whose module its tests or `gem build` would take for Minitest's or RubyGems' own
   (`lifecycle_hooks`, `date_like`);
 - that `bundle gem` would refuse or mangle (`1gem`, `my--gem`);
-- one of the Gemfile's own tools (`rubocop-rake`);
+- a gem the Gemfile's tools load, theirs included (`rubocop-rake`, `parser`): the tools' bundle
+  would resolve it to the new gem;
 - `test_helper`, whose lib/test_helper.rb would shadow the tests', or one that would write a
   template file twice (`helper`: test/test_helper.rb);
+- one of Windows' device names, a word between its dashes (`con`, `my-nul`), no file's there;
 - longer than 40 characters or deeper than 4 modules (the generated code's lines fit RuboCop's);
 - with `--exe`, whose module is CLI or VERSION (`my-c_l_i`: its command line would find another
   first).
 
-The summary is plain text: written into the README as given, Markdown in it is dprint's to check.
-As `bundle gem` does, veragem makes the git repository and adds the files, and runs no
-`bundle install`: `bin/setup` writes the lock, to commit. The generated `CONTRIBUTING.md` lists
-the first steps: the repository's settings, RubyGems' pending trusted publisher.
+### The summary
+
+The summary is plain text, as RubyGems shows it: the README shows it as written, its Markdown
+characters escaped (`_`, `` ` ``, `<`...), a URL's `://` and `www.` too, which GitHub would link
+with its escapes shown, and its spaces single, as dprint writes them; GitHub's emoji (`:gem:`)
+alone it cannot keep. It is the module's comment too, so one the gem's yard-lint or RuboCop would
+not take as its documentation is refused: a tag first, YARD's (`@param`, `(see`) or written
+informally (`Note:`, `See also:`), a RuboCop annotation (`HACK:`, `review the code`), a magic
+comment (`encoding:`, `warn_indent:`), Markdown yard-lint refuses (an em or en dash outside code,
+a `•` list marker or a code fence first), a backtick or `**` left open.
 
 ## What you get
 
 ```
-NAME.gemspec          the gem: its version from lib/NAME/version.rb, its files lib/, sig/, exe/
+NAME.gemspec          the gem: its version from lib/PATH/version.rb (`my-gem`'s lib/my/gem/), its
+                      files lib/, sig/, exe/, the README, the changelog and the licences
 Gemfile               the gemspec, then the tools; Gemfile.lock pins them (written by bin/setup)
-Rakefile              `rake`: RuboCop, Steep, the tests; `rake checks`: what CI runs;
+Rakefile              `rake`: RuboCop, Steep, the tests, yard-lint; `rake checks`: what CI runs;
                       `rake "bump[level]"`, `rake release`; `rake -T` lists them all
 Steepfile, sig/       the types; typeprof.conf.jsonc, TypeProf's editor support
-.rubocop.yml          RuboCop and its extensions
-lib/, test/           starter code: typed, documented, every line and branch tested
+.rubocop.yml          RuboCop and its extensions; .yard-lint.yml, the documentation's lint
+.simplecov, .mutineer.yml  the coverage gate; the mutation test's operators and its ignores
+lib/, test/, exe/     starter code (exe/NAME with --exe): typed, documented, every line and
+                      branch tested
 bin/setup, bin/console
 flake.nix, flake.lock the dev shell, the package (and the command's image), `nix fmt`, the checks
 .githooks/            opt-in (`rake hooks`): the quick checks before a commit, Conventional Commits
 cliff.toml, cog.toml  git-cliff's changelog, cocogitto's commit checks
 dprint.json, .editorconfig
 .github/              CI, the flake, bundler-audit, the dependency review, the release (and the
-                      image), the style checks, Dependabot, its auto-merge and its bumps'
-                      RuboCop corrections; issue and pull request templates
+                      image), the style checks, the links, Dependabot and its auto-merge; issue
+                      and pull request templates
 README, CONTRIBUTING, AGENTS, SECURITY, CODE_OF_CONDUCT, LICENSE-MIT / LICENSE-APACHE
+CITATION.cff          with --citation: the citation, its version and date `rake bump`'s
 ```
 
 The Gemfile leaves the development tools unconstrained: the lock pins them at the versions current
@@ -120,11 +211,15 @@ packages few of them, and older).
   property), the options, every file of each kind and licence rendered, parsed and kept executable,
   the gemspec read back, the values written as given whatever the locale.
 - The harness here is the template's: this repository's Gemfile, Rakefile, workflows, hooks, flake
-  and tools' configuration are the template's own files, byte for byte (`test/test_sync.rb`), so
-  the template's are checked in place by this repository's checks, and a command line's own
-  (`image.yml`) by the smoke test's command gem.
+  and tools' configuration are the template's own plain files, byte for byte (`test/test_sync.rb`;
+  but `dependabot.yml`, which moves both, `.mutineer.yml`, whose ignored mutants are the plugin's,
+  and the smoke test's workflow, the plugin's alone), so the template's are checked in place by
+  this repository's checks, and a command line's own (`image.yml`) by the smoke test's command
+  gem.
 - The smoke test (`dev/smoke.sh`, `smoke.yml`, weekly too): the plugin installed from this checkout
-  generates a gem of each kind and licence, and each passes its own `rake checks` and builds.
+  generates a gem of each kind and licence, and each, its git hooks on, passes its own
+  `rake checks`, but the links (`links.yml`'s), and builds; the citation's gem is released three
+  times (`rake bump`, then `rake release` to a local remote): its first release, a patch, a minor.
 
 ## Contributing
 
@@ -137,8 +232,8 @@ packages few of them, and older).
 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.
 

data/lib/veragem/citation.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Veragem
+  # CITATION.cff's rules beyond its values' text, as Zenodo's import takes them: who may give them,
+  # the gem's name, the author's names (no comma), alias (which Zenodo reads not) and ORCID iD, the
+  # keywords; and what its questions offer.
+  module Citation
+    # The values CITATION.cff alone writes.
+    KEYS = %i[given_names family_names alias orcid keywords].freeze
+    # An ORCID iD, bare or as its URL, spaces around it (Unicode's too): its 16th character, the
+    # check digit. Matched ASCII-downcased: /i would widen its letters to Unicode's (ſ).
+    ORCID = %r{\A[[:space:]]*(?:https?://orcid\.org/)?(\d{4}-\d{4}-\d{4}-\d{3}[\dx])[[:space:]]*\z}
+    # The ORCID iDs ORCID issues, without their check digit: those Zenodo's import takes (idutils).
+    ORCID_BLOCKS = [15_000_000..35_000_000, 900_000_000_000..900_100_000_000].freeze
+    private_constant :ORCID, :ORCID_BLOCKS
+
+    # Whether a citation's values are given: --no-given-names' false is none.
+    # @param values [Hash{Symbol => String, Boolean, nil}]
+    # @return [Boolean]
+    def self.cited?(values) = values.values_at(*KEYS).any?
+
+    # A citation's values, given only with a citation.
+    # @param values [Hash{Symbol => String, Boolean, nil}] a citation's among them
+    # @param citation [Boolean] whether the gem has CITATION.cff
+    # @return [void]
+    # @raise [Veragem::Error] one is given without a citation
+    def self.check_values(values, citation)
+      return if citation || !cited?(values)
+
+      raise Error, "--given-names, --family-names, --alias, --orcid and --keywords are CITATION.cff's: " \
+                   "they need a citation"
+    end
+
+    # The value a citation's +key+ takes, as Project.check's: an ORCID iD its URL, keywords joined by
+    # ", ".
+    # @param key [Symbol] one of KEYS
+    # @param value [String] valid UTF-8, as Project.check passes it
+    # @yieldparam field [String] a value's name, as a refusal names it
+    # @yieldparam text [String] the value, or a keyword
+    # @yieldreturn [String] it checked, one line
+    # @return [String]
+    # @raise [Veragem::Error] +key+ cannot take it
+    def self.check(key, value)
+      field = key.name.tr("_", " ")
+      case key
+      when :orcid then orcid(value)
+      when :keywords then keywords(value) { yield("keyword", it) }.join(", ")
+      # Zenodo's import reads no alias: a comma divides nothing in it
+      when :alias then yield(field, value)
+      else names(field, yield(field, value))
+      end
+    end
+
+    # The name, CITATION.cff's title: Zenodo's import refuses one under 3 characters.
+    # @param name [String] the gem's
+    # @param citation [Boolean] whether the gem has CITATION.cff
+    # @return [void]
+    # @raise [Veragem::Error] the citation cannot have the name
+    def self.check_name(name, citation)
+      return unless citation && name.length < 3
+
+      raise Error, "invalid gem name #{name} for a citation: Zenodo takes a title of 3 characters or more"
+    end
+
+    # What a citation's question offers. The citation, y where its values are given, which need one.
+    # The names, guessed from the author's words, Unicode's spaces between them: the last the family
+    # names, those before the family names the given names -- none where the author does not end
+    # with them. The alias, the GitHub user: only offered, as it may name an organization.
+    # @param key [Symbol] the question's
+    # @param values [Hash{Symbol => String, Boolean, nil}] the answers so far, checked
+    # @return [String, nil] nil for none, and for any other question
+    def self.default(key, values)
+      author = values[:author].to_s
+      case key
+      when :citation then cited?(values) ? "y" : "n"
+      when :family_names then author.split(/[[:space:]]+/).last
+      when :given_names then author[/\A(.+?)[[:space:]]+#{Regexp.escape(values[:family_names].to_s)}\z/, 1]
+      when :alias then values[:github].to_s
+      end
+    end
+
+    # An author's names, as one line: no comma, which Zenodo reads as the family names' end
+    # ("family, given"), so "Smith, Jr." would lose its given names.
+    private_class_method def self.names(field, names)
+      return names unless names.include?(",")
+
+      raise Error, "invalid #{field} #{names.inspect}: no comma, Zenodo's divide of family and given names"
+    end
+
+    # Keywords, comma-separated, as CFF's list takes them: blanks and repeats dropped, each checked
+    # by the block.
+    private_class_method def self.keywords(value, &)
+      words = value.split(",").grep_v(/\A[[:space:]]*\z/).map(&).uniq
+      return words unless words.empty?
+
+      raise Error, "invalid keywords #{value.inspect}: one or more, comma-separated"
+    end
+
+    # An ORCID iD as CFF writes it, its URL, checked as Zenodo's import checks it (idutils' is_orcid):
+    # its check digit ISO 7064 MOD 11-2's, its number in a block ORCID issues. Zenodo refuses the
+    # whole citation for a bad one.
+    private_class_method def self.orcid(value)
+      id = value.downcase(:ascii)[ORCID, 1]&.upcase
+      return "https://orcid.org/#{id}" if id && valid?(id.delete("-"))
+
+      raise Error, "invalid ORCID iD #{value.inspect}: 0000-0002-1825-0097, or its https://orcid.org/ URL"
+    end
+
+    private_class_method def self.valid?(digits)
+      *number, last = digits.chars
+      sum = number.reduce(0) { |total, digit| (total + digit.to_i) * 2 }
+      check = (12 - (sum % 11)) % 11
+      last == (check == 10 ? "X" : check.to_s) && ORCID_BLOCKS.any? { it.cover?(number.join.to_i) }
+    end
+  end
+end

data/lib/veragem/generator.rb

@@ -4,14 +4,19 @@ require "erb"
 require "fileutils"
 
 module Veragem
-  # Writes a Project's gem from template/: each `.erb` file rendered, every other copied, each with
-  # its mode; then a git repository, its files added, as `bundle gem` leaves one.
+  # Writes a Project's gem from template/: each `.erb` file rendered, every other copied, the
+  # executables executable; then a git repository, its files added, as `bundle gem` leaves one.
   module Generator
-    # __dir__ is nil only in code evaluated from a string, never in a required file
-    TEMPLATE = File.expand_path("../../template", __dir__) # steep:ignore ArgumentTypeMismatch
-    # The files a command line alone needs: its code, its test, its OCI image's workflow.
+    # template/: a generated gem's files, ERB and plain. (`|| raise`: __dir__ is nil only in code
+    # evaluated from a string, never in a required file.)
+    TEMPLATE = File.expand_path("../../template", __dir__ || raise)
+    # The files a command line alone needs: its code, its test, its OCI image's workflow and its script.
     EXE = %w[exe/%name%.erb lib/%path%/cli.rb.erb test/test_cli.rb.erb .github/workflows/image.yml
              .github/image-registries.sh].freeze
+    # The files a generated gem runs as commands: executable there, and so in git's index, which a
+    # commit keeps, where the file system has no mode (Windows: core.fileMode false).
+    EXECUTABLES = %w[.githooks/commit-msg .githooks/pre-commit .githooks/pre-push .github/image-registries.sh
+                     .github/release-notes.sh bin/console.erb bin/setup exe/%name%.erb].freeze
     # git's variables that point it at another repository (`git rev-parse --local-env-vars`, but the
     # configuration given with `git -c`), which a git hook sets: unset, the repository is the gem's.
     GIT_LOCAL = %w[GIT_ALTERNATE_OBJECT_DIRECTORIES GIT_CONFIG GIT_OBJECT_DIRECTORY GIT_DIR GIT_WORK_TREE
@@ -19,66 +24,96 @@ module Veragem
                    GIT_PREFIX GIT_SHALLOW_FILE GIT_COMMON_DIR].to_h { [it, nil] }.freeze
     # Each LICENSE-* file's SPDX identifier.
     LICENSE_FILES = { "LICENSE-MIT.erb" => "MIT", "LICENSE-APACHE.erb" => "Apache-2.0" }.freeze
+    # The citation's file, a citation's alone (--citation).
+    CITATION = "CITATION.cff.erb"
+    # The tools' resolution: this repository's Gemfile is the template's (test_sync.rb), so its lock
+    # names every gem a generated gem's tools load, theirs included.
+    TOOLS_LOCK = File.expand_path("../../Gemfile.lock", __dir__ || raise)
+    private_constant :GIT_LOCAL, :LICENSE_FILES, :CITATION, :TOOLS_LOCK
 
-    # Each template file the project takes, and its path in the gem.
-    def self.files(project)
-      skipped = skipped(project)
-      files = Dir.glob("**/*", File::FNM_DOTMATCH, base: TEMPLATE).sort.to_h { [it, path_of(it, project)] }
-      files.reject! { |file, _| skipped.include?(file) || File.directory?(File.join(TEMPLATE, file)) }
-      check(project, files.values)
-      check_command(project)
-      files
+    # Into +target+, a new directory: a failure, an interrupt included, leaves none behind.
+    # @param project [Veragem::Project] the gem
+    # @param target [String] its directory, not yet there
+    # @return [void]
+    # @raise [Veragem::Error] +target+ exists, its name cannot be generated, or a write or git fails
+    def self.generate(project, target)
+      check(project.name, exe: project.exe, citation: project.citation, target:)
+      written = files(project)
+      Dir.mkdir(target)
+      removed_unless_done(target) do
+        written.each { |file, path| write(file, File.join(target, path), project) }
+        stage(target, written.filter_map { |file, path| path if EXECUTABLES.include?(file) })
+      end
+    rescue SystemCallError => e
+      raise Error, e.message
     end
 
-    # A name can be a tool's, which the Gemfile would name twice, or a template file's: `helper`'s
-    # test would be test/test_helper.rb.
-    def self.check(project, paths)
-      raise Error, "invalid gem name #{project.name}: the Gemfile's own tool" if tools.include?(project.name)
-
-      clash = paths.tally.find { |_, count| count > 1 }
-      raise Error, "invalid gem name #{project.name}: it would write #{clash[0]} twice" if clash
+    # Every rule a gem's name meets before anything is written, its kinds' and its directory's: the
+    # questions' and the generation's one check.
+    # @param name [String] as typed
+    # @param exe [Boolean] whether the gem has a command line
+    # @param citation [Boolean] whether the gem has CITATION.cff
+    # @param target [String] its directory, not yet there
+    # @return [String] +name+
+    # @raise [Veragem::Error] the gem cannot have the name, its modules could not be checked, or
+    #   +target+ exists
+    def self.check(name, exe:, citation:, target:)
+      Name.check(name)
+      check_target(target)
+      check_name(name, exe)
+      Citation.check_name(name, citation)
+      Name.check_modules(name)
+      name
     end
 
-    # A command line names the gem's module from within it, <Gem>::CLI, whose constant lookup finds
-    # CLI and VERSION first: the gem's module cannot be named either.
-    def self.check_command(project)
-      innermost = project.modules.last
-      return unless project.exe && %w[CLI VERSION].include?(innermost)
+    # What a name and its kind decide. A gem the Gemfile's tools load (its lock's), the bundle would
+    # resolve to the new gem itself and break them. A command line names the gem's module from
+    # within it, <Gem>::CLI, whose constant lookup finds CLI and VERSION first: neither can be its
+    # module. Two files at one path: `helper`'s test would be test/test_helper.rb.
+    # @param name [String] one Name.check takes
+    # @param exe [Boolean] whether the gem has a command line
+    # @return [void]
+    # @raise [Veragem::Error] the kind cannot have the name
+    def self.check_name(name, exe)
+      raise Error, "invalid gem name #{name}: a gem the Gemfile's tools load" if tools.include?(name)
+
+      innermost = Name.modules(name).last
+      if exe && %w[CLI VERSION].include?(innermost)
+        raise Error, "invalid gem name #{name}: its command line would find another #{innermost} before its module"
+      end
 
-      raise Error, "invalid gem name #{project.name}: its command line would find another #{innermost} " \
-                   "before its module"
+      clash = templates(exe).map { path_of(it, name) }.tally.find { |_, count| count > 1 }
+      raise Error, "invalid gem name #{name}: it would write #{clash[0]} twice" if clash
     end
 
-    # The gems template/Gemfile names.
-    def self.tools = File.read(File.join(TEMPLATE, "Gemfile")).scan(/^gem "([^"]+)"/).flatten
+    # +target+ is free: neither a file nor a link, dangling ones too
+    private_class_method def self.check_target(target)
+      raise Error, "#{target} already exists" if File.exist?(target) || File.symlink?(target)
+    end
 
-    # The files another kind or licence takes.
-    def self.skipped(project)
-      licenses = LICENSE_FILES.reject { |_, spdx| project.licenses.include?(spdx) }.keys
-      project.exe ? licenses : licenses + EXE
+    private_class_method def self.files(project)
+      skipped = LICENSE_FILES.reject { |_, spdx| project.licenses.include?(spdx) }.keys
+      skipped << CITATION unless project.citation
+      (templates(project.exe) - skipped).to_h { [it, path_of(it, project.name)] }
     end
 
-    def self.path_of(file, project)
-      file.delete_suffix(".erb").gsub("%name%", project.name).gsub("%path%", project.path)
-          .gsub("%underscored%", project.underscored)
+    # The template's files a kind takes (+exe+, a command line's too), each licence's included.
+    private_class_method def self.templates(exe)
+      files = Dir.glob("**/*", File::FNM_DOTMATCH, base: TEMPLATE)
+      files.reject { File.directory?(File.join(TEMPLATE, it)) || (!exe && EXE.include?(it)) }
     end
 
-    # Into +target+, a new directory: a failure, an interrupt included, leaves none behind.
-    def self.generate(project, target)
-      raise Error, "#{target} already exists" if File.exist?(target) || File.symlink?(target)
+    # The lock's gems, its GEM section's specs (a dependency indented deeper), its lines LF's or CRLF's
+    private_class_method def self.tools(lock = File.read(TOOLS_LOCK))
+      lock[/^GEM\r?\n.*?^\r?$/m].to_s.scan(/^ {4}(\S+) \(/).flatten
+    end
 
-      files = files(project)
-      Dir.mkdir(target)
-      removed_unless_done(target) do
-        files.each { |file, path| write(File.join(TEMPLATE, file), File.join(target, path), project) }
-        git(target, "init", "--quiet", "--initial-branch=main")
-        git(target, "add", "--all")
-      end
-    rescue SystemCallError => e
-      raise Error, e.message
+    private_class_method def self.path_of(file, name)
+      file.delete_suffix(".erb").gsub("%name%", name).gsub("%path%", Name.path(name))
+          .gsub("%underscored%", Name.underscored(name))
     end
 
-    def self.removed_unless_done(target)
+    private_class_method def self.removed_unless_done(target)
       done = false
       begin
         yield
@@ -88,22 +123,36 @@ module Veragem
       end
     end
 
-    def self.write(source, destination, project)
+    private_class_method def self.write(file, destination, project)
+      source = File.join(TEMPLATE, file)
       FileUtils.mkdir_p(File.dirname(destination))
-      File.binwrite(destination, source.end_with?(".erb") ? render(source, project) : File.binread(source))
-      return unless File.executable?(source)
+      File.binwrite(destination, file.end_with?(".erb") ? render(source, project) : File.binread(source))
+      return unless EXECUTABLES.include?(file)
 
-      # executable where readable, as `chmod +x` under the umask
+      # executable where readable: the umask decides, as it does the read bits
       mode = File.stat(destination).mode
       File.chmod(mode | ((mode & 0o444) >> 2), destination)
     end
 
-    def self.render(source, project)
+    # A repository of its own, every file added, the executables' mode in the index too
+    private_class_method def self.stage(target, executables)
+      git(target, "init", "--quiet", "--initial-branch=main")
+      # --force: the user's own excludes (core.excludesFile) keep none of the gem's files out
+      git(target, "add", "--all", "--force")
+      git(target, "update-index", "--chmod=+x", "--", *executables)
+    end
+
+    # The ERB's values are +project+'s: its methods, called bare.
+    private_class_method def self.render(source, project)
       ERB.new(File.read(source, encoding: Encoding::UTF_8), trim_mode: "-").result(project.instance_eval { binding })
     end
 
-    def self.git(dir, *args)
-      system(GIT_LOCAL, "git", *args, chdir: dir) or raise Error, "git #{args.join(" ")} failed in #{dir}"
+    # system's nil: git could not run; false: it failed
+    private_class_method def self.git(dir, *args)
+      case system(GIT_LOCAL, "git", *args, chdir: dir)
+      when nil then raise Error, "cannot run git in #{dir}"
+      when false then raise Error, "git #{args.join(" ")} failed in #{dir}"
+      end
     end
   end
 end