veragem 0.1.0 → 0.2.0

data/template/.yard-lint.yml

@@ -0,0 +1,386 @@
+# yard-lint's strict preset (https://github.com/mensfeld/yard-lint): each enabled validator an
+# error, coverage at 100%.
+
+AllValidators:
+  # YARD command-line options (applied to all validators by default). The public API alone is
+  # documented: .yardopts's query, which yard-lint's coverage reads too.
+  YardOptions: []
+
+  Exclude:
+    - '\.git'
+    - 'vendor/**/*'
+    - 'node_modules/**/*'
+    - 'spec/**/*'
+    - 'test/**/*'
+
+  # error, warning, convention or never
+  FailOnSeverity: error
+
+  # percent (0-100); a lower coverage fails
+  MinCoverage: 100.0
+
+  DiffMode:
+    # --diff's base ref; ~ detects main or master
+    DefaultBaseRef: ~
+
+Documentation/UndocumentedObjects:
+  Description: 'Checks for classes, modules, and methods without documentation.'
+  Enabled: true
+  Severity: error
+  ExcludedMethods:
+    - 'initialize/0'
+    - '/^_/'          # private by convention
+  # unset: ExcludedObjects, any object's full name (a constant's too): exact, name/arity or /regex/
+  # ('MyApp::Api#call/1'); AllowedParentClasses (StandardError: its subclasses skipped)
+
+Documentation/UndocumentedMethodArguments:
+  Description: 'Checks for method parameters without @param tags.'
+  Enabled: true
+  Severity: error
+  # each parameter matched to its @param by name: a misnamed @param caught
+  CheckParameterNames: true
+  # true skips a method with no documentation at all: Documentation/UndocumentedObjects reports it
+  SkipFullyUndocumented: false
+  # unset: AllowedParentClasses; AllowedMethods, skipped (exact name, name/arity or /regex/)
+
+Documentation/UndocumentedBooleanMethods:
+  Description: 'Checks that question mark methods document their boolean return.'
+  Enabled: true
+  Severity: error
+  # unset: AllowedParentClasses
+
+Documentation/UndocumentedOptions:
+  Description: 'Detects methods with options hash parameters but no @option tags.'
+  Enabled: true
+  Severity: error
+  # unset: AllowedParentClasses
+
+Documentation/MissingReturn:
+  Description: 'Requires @return tags on all methods (opt-in for strict documentation).'
+  Enabled: true
+  Severity: error
+  ExcludedMethods:
+    - 'initialize'
+    # - '/^_/'        # private by convention, once uncommented
+  # unset: AllowedParentClasses
+
+Documentation/OrphanedDocComment:
+  Description: 'Detects YARD comment blocks with tags not attached to any documentable construct.'
+  Enabled: true
+  Severity: error
+
+Documentation/MarkdownSyntax:
+  Description: 'Detects common markdown syntax errors in documentation.'
+  Enabled: true
+  Severity: error
+
+Documentation/EmptyCommentLine:
+  Description: 'Detects empty comment lines at the start or end of documentation blocks.'
+  Enabled: true
+  Severity: error
+  EnabledPatterns:
+    Leading: true
+    Trailing: true
+
+Documentation/BlankLineBeforeDefinition:
+  Description: 'Detects blank lines between YARD documentation and method definition.'
+  Enabled: true
+  Severity: error
+  OrphanedSeverity: error
+  EnabledPatterns:
+    SingleBlankLine: true
+    OrphanedDocs: true
+  # unset: IgnoredCommentPatterns, comment lines (/regex/ or a literal at word boundaries) taken for
+  # no documentation, so no detached docstring above a blank line: commented-out code, FIXME notes
+
+Documentation/LineLength:
+  Description: 'Detects documentation comment lines that exceed the configured maximum length.'
+  Enabled: false
+  Severity: error
+  MaxLength: 120
+
+Documentation/UnderfilledLines:
+  Description: 'Detects documentation prose that wraps before using the available line width.'
+  Enabled: false  # heuristic; convention even in strict
+  Severity: convention
+  MaxLength: 120
+  MinTrailingSpace: 20
+  MinParagraphLines: 2
+  SentenceEndChars: ['.', '?', '!', ':', ';']
+  SkipNonAscii: true
+
+Documentation/TextSubstitution:
+  Description: 'Detects forbidden characters or strings in documentation and suggests replacements.'
+  Enabled: true
+  Severity: error
+  Substitutions:
+    "—": "-"    # em-dash (U+2014)
+    "–": "-"    # en-dash (U+2013)
+
+Documentation/DuplicateNamespaceComment:
+  Description: 'Detects namespaces (modules and classes) documented in more than one file.'
+  Enabled: true
+  Severity: error
+
+Documentation/ReferenceTypo:
+  Description: 'Detects probable typos in method and constant references.'
+  Enabled: true
+  Severity: error
+
+Tags/Order:
+  Description: 'Enforces consistent ordering of YARD tags.'
+  Enabled: true
+  Severity: error
+  EnforcedOrder:
+    - param
+    - option
+    - yield
+    - yieldparam
+    - yieldreturn
+    - return
+    - raise
+    - see
+    - example
+    - note
+    - todo
+
+Tags/InvalidTypes:
+  Description: 'Validates type definitions in @param, @return, @option tags.'
+  Enabled: true
+  Severity: error
+  YardOptions: [] # the public API alone, as the others: it reads every visibility otherwise
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+    - raise
+  # flags a CamelCase type neither a loaded constant nor defined in the code: a typo, or a
+  # dependency's type, which ExtraTypes admits
+  StrictConstantNames: true
+
+Tags/TypeSyntax:
+  Description: 'Validates YARD type syntax using YARD parser.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+    - raise
+
+Tags/MeaninglessTag:
+  Description: 'Detects @param/@option tags on classes, modules, or constants.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  InvalidObjectTypes:
+    - class
+    - module
+    - constant
+
+Tags/MissingYield:
+  Description: 'Detects methods that yield to a block without a @yield, @yieldparam, or @yieldreturn tag.'
+  Enabled: true
+  Severity: error
+  YardOptions: [] # the public API alone, as the others: it reads every visibility otherwise
+
+Tags/CollectionType:
+  Description: 'Validates Hash collection syntax consistency.'
+  Enabled: true
+  Severity: error
+  EnforcedStyle: long  # 'long' for Hash{K => V} (YARD standard), 'short' for {K => V}
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+    - raise
+
+Tags/TagTypePosition:
+  Description: 'Validates type annotation position in tags.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  # type_after_name, @param name [Type] (YARD's), or type_first, @param [Type] name
+  EnforcedStyle: type_after_name
+
+Tags/ApiTags:
+  Description: 'Enforces @api tags on public objects.'
+  Enabled: false
+  Severity: error
+  AllowedApis:
+    - public
+    - private
+    - internal
+
+Tags/OptionTags:
+  Description: 'Requires @option tags for methods with options parameters.'
+  Enabled: true
+  Severity: error
+  YardOptions: [] # the public API alone, as the others: it reads every visibility otherwise
+
+Tags/ExampleSyntax:
+  Description: 'Validates Ruby syntax in @example tags.'
+  Enabled: true
+  Severity: error
+  # true skips @example console transcripts (irb or pry, `=>` output, `$` prompts): off, so no real
+  # syntax error hides
+  SkipNonRuby: false
+
+Tags/ExampleStyle:
+  Description: 'Validates code style in @example tags using RuboCop/StandardRB.'
+  Enabled: false  # requires RuboCop or StandardRB
+  Severity: convention
+  # unset: Linter (auto, rubocop, standard or none); SkipPatterns, examples skipped ('/skip-lint/i')
+
+Tags/RedundantParamDescription:
+  Description: 'Detects meaningless parameter descriptions that add no value.'
+  Enabled: true
+  Severity: error
+  CheckedTags:
+    - param
+    - option
+  Articles:
+    - The
+    - the
+    - A
+    - a
+    - An
+    - an
+  MaxRedundantWords: 6
+  GenericTerms:
+    - object
+    - instance
+    - value
+    - data
+    - item
+    - element
+  EnabledPatterns:
+    ArticleParam: true
+    PossessiveParam: true
+    TypeRestatement: true
+    ParamToVerb: true
+    IdPattern: true
+    DirectionalDate: true
+    TypeGeneric: true
+    ArticleParamPhrase: true
+
+Tags/InformalNotation:
+  Description: 'Detects informal tag notation patterns like "Note:" instead of @note.'
+  Enabled: true
+  Severity: error
+  CaseSensitive: false
+  RequireStartOfLine: true
+  # true skips indented Markdown code blocks too, not only fenced ones: off, as list continuations
+  # and wrapped prose are indented too
+  SkipIndentedCodeBlocks: false
+  Patterns:
+    Note: '@note'
+    IMPORTANT: '@note'
+    Important: '@note'
+    Todo: '@todo'
+    TODO: '@todo'
+    FIXME: '@todo'
+    See: '@see'
+    See also: '@see'
+    Warning: '@note'
+    Deprecated: '@deprecated'
+    Author: '@author'
+    Version: '@version'
+    Since: '@since'
+    Returns: '@return'
+    Raises: '@raise'
+    Example: '@example'
+
+Tags/NonAsciiType:
+  Description: 'Detects non-ASCII characters in type annotations.'
+  Enabled: true
+  Severity: error
+  ValidatedTags:
+    - param
+    - option
+    - return
+    - yieldreturn
+    - yieldparam
+    - raise
+
+Tags/TagGroupSeparator:
+  Description: 'Enforces blank line separators between different YARD tag groups.'
+  Enabled: false
+  Severity: error
+  TagGroups:
+    param: [param, option]
+    return: [return]
+    error: [raise, throws]
+    example: [example]
+    meta: [see, note, todo, deprecated, since, version, api]
+    yield: [yield, yieldparam, yieldreturn]
+  RequireAfterDescription: false
+
+Tags/TagSeparator:
+  Description: 'Enforces a blank line between every consecutive YARD tag.'
+  Enabled: false
+  Severity: error
+  Exempt: []
+  RequireAfterDescription: false
+
+Tags/ForbiddenTags:
+  Description: 'Detects forbidden tag and type combinations.'
+  Enabled: false
+  Severity: error
+  ForbiddenPatterns: []
+  # e.g. {Tag: return, Types: [void]}; a Tag without Types forbids the tag outright
+
+Tags/OverloadConsistency:
+  Description: 'Checks the tags of each @overload against its own signature.'
+  Enabled: true
+  Severity: error
+
+Warnings/SyntaxError:
+  Description: 'Detects Ruby files YARD cannot parse (syntax errors).'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownTag:
+  Description: 'Detects unknown YARD tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownDirective:
+  Description: 'Detects unknown YARD directives.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidTagFormat:
+  Description: 'Detects malformed tag syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/InvalidDirectiveFormat:
+  Description: 'Detects malformed directive syntax.'
+  Enabled: true
+  Severity: error
+
+Warnings/DuplicatedParameterName:
+  Description: 'Detects duplicate @param tags.'
+  Enabled: true
+  Severity: error
+
+Warnings/UnknownParameterName:
+  Description: 'Detects @param tags for non-existent parameters.'
+  Enabled: true
+  Severity: error
+
+Semantic/AbstractMethods:
+  Description: 'Ensures @abstract methods do not have real implementations.'
+  Enabled: true
+  Severity: error

data/template/.yardopts

@@ -0,0 +1,2 @@
+--query 'object.visibility == :public'
+lib/**/*.rb

data/template/AGENTS.md.erb

@@ -4,58 +4,83 @@ Repository rules for `<%= name %>`. These apply to every contributor, human or A
 Adding a dependency or a tool, the tests' rules and the release are
 [CONTRIBUTING.md](CONTRIBUTING.md)'s.
 
-## 1. The lint and type policy is the design
+## 1. Lints and Types
 
-RuboCop runs with its defaults and every new cop as it ships (`NewCops: enable`), its Minitest,
-packaging, performance and Rake extensions on, and the project indexed first (`UseProjectIndex`, the
-rubydex gem) for the cops that look across files (`.rubocop.yml`). Steep checks `lib/` against the
-signatures in `sig/`, its strictest diagnostics on (`Steepfile`): every method of `lib/` is declared
-in `sig/`, and a warning fails as an error does. Gemfile.lock pins both, so the verdict is the same
-locally and in CI.
-
-**Never silence a new cop or diagnostic wholesale.** Either fix the site, or configure it in
-`.rubocop.yml` (or the Steepfile) with a comment saying why it is wrong for this codebase.
+RuboCop runs with its defaults, a few cops beyond them, and every new cop as it ships
+(`NewCops: enable`), its Minitest, packaging, performance and Rake extensions on, and the project
+indexed first (`UseProjectIndex`, the rubydex gem) for the cops that look across files
+(`.rubocop.yml`). Steep checks `lib/` against the signatures in `sig/`, its `strict` diagnostics on
+(`Steepfile`): every method of `lib/` is declared in `sig/`, a warning fails as an error does, and
+so does a call on an untyped receiver (`rake steep:typed`, from `steep stats`). Gemfile.lock pins
+both, so the verdict is the same locally and in CI. YARD documents `lib/`, and yard-lint holds it
+(`.yard-lint.yml`).
 
 The shell is held as the code is: shfmt formats it (`.editorconfig` holds its style) and it passes
 ShellCheck. The Nix is nixfmt's. The workflows pass actionlint and, with Dependabot's
 configuration, zizmor's security audit.
 
-## 2. Types: signatures by hand, TypeProf to start them
-
-`sig/` is written by hand and Steep holds `lib/` to it. `bundle exec rake typeprof` prints the
-signatures TypeProf infers from `lib/`: a start for a new method's, never a replacement for
-reading them -- it says `untyped` where it cannot tell. A signature is as narrow as the code
-allows: `untyped` only where the value truly is any value.
-
-## 3. Silence a cop or a diagnostic at the site, with a reason
+### 1.1. RuboCop
+
+- Before finishing, check the files you changed since your branch left main with
+  `bundle exec rake rubocop:changed` (every file where there is no origin/main yet).
+- Fix offenses with `bundle exec rubocop -a FILES`. Don't use `-A` unless asked.
+- If an offense is unclear, run `bundle exec rubocop --explain Department/CopName`.
+- Don't edit `.rubocop.yml` to make offenses go away.
+- When an offense has to stay, disable the cop on that line, or the next (`# rubocop:disable-next`
+  on the line above), and say why:
+  `# rubocop:disable Department/CopName -- the reason`.
+
+### 1.2. YARD
+
+- Every public object of `lib/` is documented (yard-lint, at 100% coverage; `.yardopts` keeps the
+  public API): what it is for, then its tags -- each `@param`, `@yield`, `@return` and `@raise`, in
+  that order (Tags/Order) -- their types the signatures' in YARD's syntax (`Array<String>`,
+  `Hash{Symbol => String}`, `String, nil`). A private one takes a comment only as §2 has it, and no
+  tags: its signature holds its types.
+- `bundle exec rake yard_lint` lints it (`yard-lint lib --stats`); `bundle exec rake yard` writes
+  it to `doc/`.
+- `bundle exec yard list --query '@return && @param'` lists the objects a query of the tags
+  matches.
+- `bundle exec rake graph` prints the classes and modules as a Graphviz graph
+  (`yard graph --protected --private --full --dependencies`): `| dot -Tsvg -o graph.svg`.
+
+### 1.3. Types: signatures by hand, TypeProf to start them
+
+`sig/` is written by hand and Steep holds `lib/` to it, so every method's types are there, a private
+one's too (it has no YARD tags): look a method's up in `sig/<%= path %>.rbs`.
+`bundle exec rake typeprof` prints the signatures TypeProf infers from `lib/`: a start for a new
+method's, never a replacement for reading them -- it says `untyped` where it cannot tell. A
+signature is as narrow as the code allows: `untyped` only where the value truly is any value, and a
+call on one fails `rake steep:typed` until `when String` or an assertion (`value #: String`) narrows
+it (`value.is_a?(String)` is itself such a call). A library Steep has no signatures of is an error
+to it: name one that ships them in the Steepfile (`library "json"`), take a gem's from
+gem_rbs_collection (CONTRIBUTING.md), and declare in `sig/` what `lib/` calls of one with none. When
+a diagnostic has to stay, ignore it on its line, the reason on the line above (text after the
+diagnostic's name voids the ignore; an ignore leaves an untyped call untyped):
 
 ```ruby
-eval(code) # rubocop:disable Security/Eval -- code is this gem's own, never its input
-
-# the library declares no signature -- above: text after Steep's diagnostic name voids the ignore
+# the library's signature lacks the method
 value = client.fetch # steep:ignore NoMethod
 ```
 
-Name the cop or diagnostic. A reason that restates the rule is not a reason: say what makes the
-site safe. RuboCop reports a disable that no longer applies (`Lint/RedundantCopDisableDirective`),
-so a justification cannot outlive the code it justified.
-
-## 4. Comments: only what is essential
+## 2. Comments: only what is essential
 
 A comment says what the code cannot: why it is so, the source it follows, the constraint it keeps.
 Make it concise and precise -- a line where a line does -- and never restate the code: that is
 noise, and it goes stale. A change that falsifies a comment rewrites it.
 
-## 5. Commits
+## 3. Commits
 
-[Conventional Commits](https://www.conventionalcommits.org/) are enforced by `cog check` locally
-and in CI. The changelog is generated from the commits (`cliff.toml`), so the subject line is
-user-facing text; `chore`, `ci` and `style` commits stay out of it, and `!` or a `BREAKING CHANGE`
-footer lists a commit first:
+[Conventional Commits](https://www.conventionalcommits.org/) are enforced by `cog check` locally and
+in CI. The changelog is generated from the commits (`cliff.toml`) and shows each one's subject
+alone, so a subject is user-facing text, and a commit holds only the change its subject names:
+anything else gets its own commit. The changelog lists every commit cog checks but the release's
+own, `chore` and `ci` as Miscellaneous Tasks, and `!` or a `BREAKING CHANGE` footer lists a commit
+first:
 
 ```
 feat: accept the name as a symbol too
-fix: strip a trailing newline from the name
+fix: strip Unicode whitespace from the name too
 docs: explain the greeting's fallback
 build(deps): depend on json
 ```
@@ -64,12 +89,25 @@ The git hooks (`bundle exec rake hooks`) check the same before a commit and a pu
 them with `--no-verify`. `git revert` writes `Revert "..."`, which CI refuses: reword it as
 `revert: ...`.
 
-## 6. Before you claim a change is done
-
-Run `bundle exec rake checks`. It is what CI runs: RuboCop, Steep, the tests with every line,
-branch and method covered, bundler-audit, dprint, the commit messages, the shell, the workflows,
-and the flake's checks. Reporting "done" on a change that has not passed it is the one thing that
-wastes the most time here.
+## 4. Before you claim a change is done
+
+Run `bundle exec rake checks`. It runs CI's gates: RuboCop, Steep, the tests with every line, branch
+and method covered and no warning of their own, yard-lint, bundler-audit, dprint, the commit
+messages, the shell, the workflows, the links (CI's, monthly), the mutations of the changed lines
+(CI's, of every line), and the flake's checks. It stops at the first that fails: run the rest by
+name (`bundle exec rake mutation:changed nix`). Reporting "done" on a change that has not passed it
+is the one thing that wastes the most time here.
+
+A fix comes with a test that fails without it: run it before the fix, then after. The gates hold
+what the tests run, so they pass code nothing needs, which a change deletes rather than hides:
+
+- a signature with no method behind it (Steep accepts one), a `require` nothing needs, a constant
+  nothing reads;
+- an option no test sets: its default alone runs;
+- code kept from coverage (`# simplecov:disable`, a `.simplecov` skip): mutineer scores no mutant no
+  test runs, so it passes both. `.simplecov` skips only what loads before coverage starts
+  (`version.rb`), and `.mutineer.yml` ignores only a mutant that keeps the behaviour, with its
+  reason.
 
 If a check fails for reasons unrelated to your change, say so explicitly rather than working
 around it -- a broken check that everyone routes around stops protecting anything.

data/template/CITATION.cff.erb

@@ -0,0 +1,50 @@
+# The citation GitHub's "Cite this repository" and Zenodo read (Citation File Format 1.2.0);
+# `rake bump` sets version and date-released at each release.
+cff-version: 1.2.0
+message: "If you use this software, please cite it using the metadata from this file."
+title: <%= yaml(name) %>
+abstract: <%= yaml(summary) %>
+authors:
+  - family-names: <%= yaml(family_names) %>
+<%- if given_names -%>
+    given-names: <%= yaml(given_names) %>
+<%- end -%>
+<%- if alias_name -%>
+    alias: <%= yaml(alias_name) %>
+<%- end -%>
+<%- if orcid -%>
+    orcid: "<%= orcid %>"
+<%- end -%>
+<%- if keywords -%>
+keywords:
+<%- keywords.each do |keyword| -%>
+  - <%= yaml(keyword) %>
+<%- end -%>
+<%- end -%>
+version: "0.1.0"
+date-released: "<%= today %>"
+<%- if licenses.one? -%>
+license: <%= licenses.first %>
+<%- else -%>
+# MIT OR Apache-2.0, as CFF writes an OR; Zenodo's import refuses a list, so it archives no release
+# until zenodo/zenodo-rdm#1509 is fixed
+license:
+<%- licenses.each do |spdx| -%>
+  - <%= spdx %>
+<%- end -%>
+<%- end -%>
+repository-code: "https://github.com/<%= github %>/<%= name %>"
+repository-artifact: "https://rubygems.org/gems/<%= name %>"
+# the API documentation rubydoc.info serves for each gem on RubyGems: there from the first release
+url: "https://rubydoc.info/gems/<%= name %>"
+# Zenodo's DOIs, to uncomment once it has archived a release: the concept DOI, every version's
+# (Zenodo's "Cite all versions"), and a version's own -- minted after its release is tagged, so the
+# file can hold an earlier version's alone
+# doi: "10.5281/zenodo.0000000"
+# identifiers:
+#   - type: doi
+#     value: "10.5281/zenodo.0000000"
+#     description: "The concept DOI, of every version"
+#   - type: doi
+#     value: "10.5281/zenodo.0000001"
+#     description: "The DOI of version 0.1.0"

data/template/CODE_OF_CONDUCT.md.erb

@@ -10,7 +10,7 @@ This repository is for technical development.
   removed.
 
 <%- if email -%>
-Report conduct concerns to the maintainers at <%= email %>.
+Report conduct concerns to the maintainers at <%= markdown(email) %>.
 <%- else -%>
 Report conduct concerns to the maintainers, or through GitHub's
 [report content](https://docs.github.com/en/communities/maintaining-your-safety-on-github/reporting-abuse-or-spam)