crap4ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55e5f45f41b35122c6ad4b4894e3d5e496af3842c4a4f28e8172806c45d8d620
-  data.tar.gz: '0279b34834aeba13649a0f124b6064b44a92fdffa868ad5f1a893e56a9067473'
+  metadata.gz: e5227286a59e47edaf5fe8e20c8ce9c1abe6391b4f95304f8352c6b98fdf53dd
+  data.tar.gz: 2a569cea7aa8f9172d2ce2c854dec0d62c76ae3e73f1f3618f911b3d55c6deff
 SHA512:
-  metadata.gz: 555c402719177c91525c68611ee3e5e88ae0c674bf74a1f2b477857d4e97e017cfe50a2674d829e46a9fd7c16a252d69aaf97953ebb811d6a98a733596898157
-  data.tar.gz: 0e9ea5f5d64473c6547faaad0cc4126a0d7a1c0236c37c0a457cdb1e69ae5d828160619ddce843033df76c723c45440f64049b071a5bf74846ad11447700a1d4
+  metadata.gz: 25f98c5d9ca08faa51388483dc63735238f4dc0a20daf13a80ad104086e48c36d91fb2204a2d4e25a903ce17ccdd510cb8059be09b47ea4a582921fee1a5b649
+  data.tar.gz: b819b05ff07ec266c2316f77b317b2f45975e4ebd7ed2e4f325aea8553a2fa767033d4351086ab67979f9230523497f1d91aab3f49fad540ae911c529fd4dbce

data/CHANGELOG.md

@@ -1,7 +1,33 @@
 # Changelog
 
+All notable changes are recorded here using [Keep a Changelog 2.0.0](https://keepachangelog.com/en/2.0.0/).
+Version numbers follow [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) as defined in the [versioning policy](VERSIONING.md).
+
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-28
+
+### Changed
+
+- Use RuboCop 1.92.1 complexity rules, including iteration blocks, safe-navigation discounts, rescue groups, and nested bodies, while excluding a method's own parameter defaults.
+- Discover bare `define_method` calls with literal symbol or string names and blocks.
+- Reject literal `define_method` names that cannot be represented in UTF-8, preserving the previous snapshot.
+- Report N/A for coverage and CRAP when a body shares its declaration line. Unknown scores pass a requested threshold only when their maximum possible score fits it; otherwise the check returns exit 1. These scoring and exit-code changes require a minor release. Regenerate coverage and snapshots and review thresholds when upgrading.
+
+### Fixed
+
+- Include executable interpolation lines when a method ends with a heredoc.
+- Discover explicit method definitions inside parameter defaults and superclass expressions.
+- Compare exact CRAP scores with decimal thresholds without floating-point rounding errors.
+- Avoid attributing trailing code on a method's closing line to the method, and escape control characters in displayed method names.
+
+## [0.1.1] - 2026-10-28
+
+### Changed
+
+- Document single-file analysis, contribution and private reporting policies, and the public compatibility policy.
+- Add a YARD maintainer reference and link to gem documentation from RubyGems metadata.
+
 ## [0.1.0] - 2026-10-28
 
 ### Added
@@ -16,5 +42,7 @@
 
 - Split CLI execution, AST discovery, and coverage loading into smaller methods without changing their behavior or scoring rules.
 
-[Unreleased]: https://github.com/svyatov/crap4ruby/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/svyatov/crap4ruby/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/svyatov/crap4ruby/compare/v0.1.1...v0.2.0
+[0.1.1]: https://github.com/svyatov/crap4ruby/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/svyatov/crap4ruby/releases/tag/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,90 @@
+# Contributor Covenant 3.0 Code of Conduct
+
+## Our Pledge
+
+We pledge to make our community welcoming, safe, and equitable for all.
+
+We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant.
+
+
+## Encouraged Behaviors
+
+While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language.
+
+With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including:
+
+1. Respecting the **purpose of our community**, our activities, and our ways of gathering.
+2. Engaging **kindly and honestly** with others.
+3. Respecting **different viewpoints** and experiences.
+4. **Taking responsibility** for our actions and contributions.
+5. Gracefully giving and accepting **constructive feedback**.
+6. Committing to **repairing harm** when it occurs.
+7. Behaving in other ways that promote and sustain the **well-being of our community**.
+
+
+## Restricted Behaviors
+
+We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct.
+
+1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop.
+2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people.
+3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits.
+4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community.
+5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission.
+6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group.
+7. Behaving in other ways that **threaten the well-being** of our community.
+
+### Other Restrictions
+
+1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions.
+2. **Failing to credit sources.** Not properly crediting the sources of content you contribute.
+3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community.
+4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors.
+
+
+## Reporting an Issue
+
+Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm.
+
+When an incident does occur, it is important to report it promptly. To report a possible violation, email [leonid@svyatov.com](mailto:leonid@svyatov.com). Leonid Svyatov monitors this address and will respond within 14 days.
+
+Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution.
+
+
+## Addressing and Repairing Harm
+
+If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped.
+
+1) Warning
+   1) Event: A violation involving a single incident or series of incidents.
+   2) Consequence: A private, written warning from the Community Moderators.
+   3) Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations.
+2) Temporarily Limited Activities
+   1) Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation.
+   2) Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members.
+   3) Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over.
+3) Temporary Suspension
+   1) Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation.
+   2) Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions.
+   3) Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted.
+4) Permanent Ban
+   1) Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member.
+   2) Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior.
+   3) Repair: There is no possible repair in cases of this severity.
+
+This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community.
+
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+
+## Attribution
+
+This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/).
+
+Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/)
+
+For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion).
+

data/CONTRIBUTING.md

@@ -1,15 +1,54 @@
 # Contributing
 
-Use Ruby 3.3 or newer. Install dependencies and run the suite:
+Outside contributions are welcome. This guide defines the project's [acceptance criteria](#acceptance-criteria).
+
+## Development
+
+Use Ruby 3.3 or newer. Install [Betterleaks](https://github.com/betterleaks/betterleaks) with the `betterleaks` command on your PATH.
+Set up dependencies and Git hooks, then run the suite:
 
 ```sh
-bundle install
+bin/setup
 bundle exec rake
 ```
 
-The default check runs tests with fresh SimpleCov coverage and requires every library method's CRAP score to be at most 10.
+Before each commit, hooks run Ruby lint checks and scan staged changes for secrets and whitespace errors.
+Commit messages must use Conventional Commits.
+Before each push, hooks run `bundle exec rake`.
+Put machine-specific hook settings in the ignored `lefthook-local.yml` file.
+
+The default check, also available as `bundle exec rake check`, runs RuboCop, Steep, tests with fresh SimpleCov coverage, YARD validation, and dependency audits.
+Every Ruby file must have 100% typed calls.
+Every library method's CRAP score must be at most 10.
 Use `bundle exec rake test` for tests alone. Open `coverage/index.html` to inspect line coverage.
 
+Run `bundle exec rake lint` to check Ruby style, formatting, performance, Minitest assertions, and Rake tasks.
+Run `bundle exec rake format` to apply RuboCop's safe corrections, then review the diff.
+RuboCop targets Ruby 3.3 and preserves the project's double-quoted strings and compact hashes.
+YARD and CRAP enforce documentation and complexity requirements; RuboCop's overlapping documentation and metrics checks are disabled.
+
+Run `bundle exec rake audit` to check both the development and release lockfiles for known vulnerabilities and insecure gem sources.
+The audit updates RubySec's advisory database over the network and stores it in the ignored `.cache/` directory.
+The default check and pre-push hook therefore require network access.
+
+Run `bundle exec rake types` for type checks alone.
+Keep library signatures in `sig/` and signatures for tests and development tools in `sig-development/`.
+The type gate rejects unchecked Ruby files, untyped signatures, and any call that Steep cannot type.
+Add new source locations to `Steepfile` when the gate reports an unchecked file.
+
+Document public library methods and data readers with YARD summaries, parameter types, return types, and relevant exceptions.
+Explain private methods when their constraints or side effects need context.
+Keep types consistent with `sig/` and include examples when they clarify usage.
+The Ruby reference is for maintainers and does not extend the [public compatibility policy](VERSIONING.md).
+
+Run `bundle exec rake docs` to generate the reference, including private methods, then open `doc/index.html`.
+Run `bundle exec rake docs:check` to reject YARD warnings, undocumented public methods, and readers without explicit documentation and return types.
+Generated files in `doc/` and `.yardoc/` are ignored.
+
+After changing dependencies, use Ruby 3.3 and the Bundler version recorded in `Gemfile.lock`.
+Run `bundle exec rake lock` to refresh both lockfiles and their checksums.
+CI installs the release tools from `gemfiles/release/Gemfile.lock` in frozen mode.
+
 Add a regression test for a behavior change. Use temporary projects for filesystem, Git, coverage, and CLI tests.
 Keep analyzed code out of the tool's process. Preserve the previous snapshot when analysis fails.
 
@@ -17,3 +56,21 @@ For defect reports, include the Ruby version, command, expected result, actual r
 Coverage defects also need a matching excerpt from `.resultset.json`. Remove application secrets before sharing examples.
 
 Changes use Conventional Commits. Keep code, tests, and documentation for one behavior in a focused commit.
+
+## Acceptance criteria
+
+- Keep each change focused on one behavior or correction.
+- Include tests for new functionality and regression tests for behavior changes.
+- Pass `bundle exec rake`, including the method CRAP limit.
+- Update documentation when user-visible behavior changes.
+- Follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Submit a change
+
+Fork the repository and create a branch from `main`. Commit your change, push the branch to your fork, and open a pull request against `svyatov/crap4ruby:main`.
+Describe the behavior being changed and any effect on existing users. Link the related issue when one exists.
+
+## Decisions and succession
+
+Leonid Svyatov (@svyatov) is the sole maintainer and decides which changes to merge and release.
+No succession arrangement exists if he stops maintaining the project.

data/README.md

@@ -2,9 +2,10 @@
 
 crap4ruby identifies complex, under-tested Ruby methods using the Change Risk Anti-Pattern (CRAP) metric.
 
-- Analyzes Ruby 3.3+ source with Prism without loading application code.
-- Reads SimpleCov reports, including legacy formats and multiple test suites.
-- Prints method scores and writes the snapshot format used by [crapper](https://github.com/unclebob/crapper).
+- Analyzes Ruby 3.3+ methods without loading application code.
+- Ranks methods using complexity and test coverage, rather than complexity alone.
+- Reads existing SimpleCov reports and merges coverage across test suites.
+- Checks one file, directories, or only files changed in Git.
 
 ## Install
 
@@ -14,12 +15,22 @@ Ruby 3.3 or newer is required.
 gem install crap4ruby
 ```
 
-In the project you want to measure:
+In an empty directory, create a sample and analyze it:
+
+```sh
+printf 'def eligible?(age) = age >= 18\n' > sample.rb
+crap4ruby --no-coverage sample.rb
+# Reports eligible? with CC 1; coverage and CRAP are N/A.
+# Writes .metrics/crap.edn.
+```
+
+In an existing project, select the source you want to measure:
 
 ```sh
 crap4ruby --no-coverage
 crap4ruby
 crap4ruby --threshold 30
+crap4ruby app/models/user.rb
 crap4ruby app/models lib/billing
 ```
 
@@ -35,7 +46,7 @@ Run these commands from this checkout with Ruby 3.3 or newer:
 ```sh
 bundle install
 gem build crap4ruby.gemspec
-gem install ./crap4ruby-0.1.0.gem
+gem install ./crap4ruby-0.2.0.gem
 ```
 
 To use Bundler in the measured project, add this checkout to that project's `Gemfile`:
@@ -48,7 +59,7 @@ Then run `bundle install` and `bundle exec crap4ruby` in that project.
 
 ## Set up coverage
 
-[SimpleCov](https://github.com/simplecov-ruby/simplecov) must start before the application loads. Add it to the measured project's test dependencies:
+[SimpleCov](https://github.com/simplecov-ruby/simplecov) must start before the application loads. Add it to the measured project's `Gemfile`:
 
 ```ruby
 gem "simplecov", require: false, group: :test
@@ -85,7 +96,7 @@ crap4ruby does not configure SimpleCov, delete reports, install dependencies, or
 | `--use-existing-coverage` | Explicitly select the default: read reports without running tests. |
 | `--coverage-command COMMAND` | Run a shell command that refreshes the selected report. |
 | `--no-coverage` | Report complexity with unknown coverage and CRAP. |
-| `--threshold NUMBER` | Exit 2 when any unrounded score exceeds this finite, nonnegative value. |
+| `--threshold NUMBER` | Check this finite, nonnegative limit; exit 2 for a measured violation, or 1 if an unknown score could exceed it. |
 | `-h`, `--help` | Print usage. |
 | `-v`, `--version` | Print the gem version. |
 
@@ -98,38 +109,49 @@ Discovery includes `.rb` files. It skips hidden directories, test/spec files, an
 Test filenames are `test_*.rb`, `spec_*.rb`, `*_test.rb`, and `*_spec.rb`.
 An explicitly named file overrides these exclusions. Directory traversal does not follow symbolic links.
 
-Exit 0 means analysis succeeded. Exit 1 means invalid usage, unreadable or invalid input, a Git failure, or a coverage command failure.
-Exit 2 means analysis succeeded but exceeded the threshold. No threshold applies unless you set one.
-Every successful analysis replaces the snapshot, including filtered analyses and empty selections.
+Exit 0 means analysis succeeded and any requested threshold was verified. Exit 1 means invalid usage, unreadable or invalid input, a Git failure, a coverage command failure, or an uncertain threshold result.
+Exit 2 means a measured score exceeded the threshold. A measured violation takes precedence over uncertainty. No threshold applies unless you set one.
+Decimal thresholds are compared exactly with the computed scores, before display rounding.
+For unknown scores, the check uses the maximum possible score, `CC^2 + CC`, at zero coverage. If this maximum fits the threshold, the method passes; otherwise, the check returns exit 1 and names the method. Its displayed score remains N/A. This also applies with `--no-coverage`.
+For example, an unknown score at CC 2 passes a threshold of 6, but cannot pass a threshold of 5. Supply fresh, measurable coverage or adjust the limit to resolve uncertainty.
+Every completed analysis replaces the snapshot, including filtered analyses, empty selections, and failed threshold checks.
 
 ## Complexity and coverage
 
-The formula uses a coverage fraction between 0 and 1:
+The scoring engine uses this formula, with coverage expressed as a fraction between 0 and 1:
 
 ```text
 CRAP = CC^2 * (1 - coverage)^3 + CC
 ```
 
-Cyclomatic complexity (CC) starts at 1. Each of these adds 1:
+The formula follows the [original CRAP definition](https://www.artima.com/weblogs/viewpost.jsp?thread=210575). This tool uses line coverage as a proxy for the original definition's basis path coverage. These measurements are not equivalent.
+
+Cyclomatic complexity (CC) follows [RuboCop 1.92.1](https://github.com/rubocop/rubocop/blob/aa228eb03094d66aca26664839ca14b10d76f702/lib/rubocop/cop/metrics/cyclomatic_complexity.rb). It starts at 1. Each of these adds 1:
 
 - `if`, `elsif`, `unless`, and ternary conditions, including modifier forms.
-- `while`, `until`, and `for` loops.
-- Each `when` or pattern-matching `in` clause, including a separate increment for a guard condition.
-- Each rescue clause and rescue modifier.
-- Each `&&`, `||`, `and`, `or`, `&&=`, `||=`, and safe-navigation operation.
+- `while`, `until`, and `for` loops, except post-test `begin ... end while/until` forms.
+- Each `when` or pattern-matching `in` clause. A pattern guard's `if`/`unless` wrapper adds nothing; decisions within its condition still count.
+- Each rescue group, regardless of its number of clauses, and each rescue modifier.
+- Each `&&`, `||`, `and`, `or`, `&&=`, and `||=` operation.
+- Each safe-navigation operation, except repeated use of the same local receiver until its next assignment.
+- Each ordinary block or block argument passed to a [known iteration method](https://github.com/rubocop/rubocop/blob/aa228eb03094d66aca26664839ca14b10d76f702/lib/rubocop/cop/metrics/utils/iterating_block.rb), such as `map`, `each`, or `reduce`.
 
 A `when` clause adds 1 regardless of its number of alternatives. `else` and `ensure` add nothing.
 Decisions inside ordinary blocks and lambdas belong to their enclosing method.
-Decisions in parameter defaults also count; coverage still measures only the body.
-Nested methods are separate entries. Their bodies and nested class/module bodies do not increase the enclosing method's score.
-Calling `each`, `map`, or another iterator does not itself add complexity.
+The method's own parameter defaults do not count. Nested definitions and their defaults, including nested class/module bodies, contribute decisions to the enclosing body, as in RuboCop.
+The safe-navigation discount follows local variable names across that entire body, including nested scopes, in RuboCop's AST traversal order. Assignments reset it; parameters, pattern bindings, and named regexp captures do not.
+RuboCop 1.92.1 does not add an iteration point for numbered or implicit-`it` blocks. This tool preserves that version's behavior. Iterator calls without a block add nothing.
+Nested methods are also separate entries. Definitions inside parameter defaults and superclass expressions are discovered too.
 
 Coverage is the fraction of executable method-body lines with positive hit counts.
-Separate `def` headers are excluded: loading a definition does not prove that tests called its method.
+Declaration lines and nested method/class/module bodies are excluded from coverage. Loading a definition does not prove that tests called its method.
+When the body shares a line with its declaration, coverage and CRAP are N/A, even if that line has hits. This includes ordinary inline methods, one-line endless methods, and inline `define_method` blocks. Put the body on separate lines to obtain measurable coverage.
+Coverage is also N/A when a selected body line contains trailing code after the definition, including enclosing delimiters that cannot be separated from that line's hit count. Put the closing delimiter on its own line. Comments and empty statement separators do not trigger this check.
+Executable heredoc interpolation lines are included, even when the heredoc is the method's final expression.
 Null lines do not enter the denominator. Multiple suites are merged by covered-line union, without applying an age cutoff.
 Coverage paths must match absolute source paths or paths relative to the project root; unrelated checkout prefixes are not guessed.
 
-A method absent from a valid report receives 0% coverage. A body with no measurable lines receives N/A.
+A method with unambiguous body lines in a file absent from a valid report receives 0% coverage. A reported body with no measurable lines receives N/A.
 Missing or malformed reports stop analysis unless `--no-coverage` is explicit.
 Reports are accepted as supplied; generate fresh coverage after changing source files.
 
@@ -153,12 +175,15 @@ A filtered run writes only its selected methods. Reopened classes and repeated d
 
 ## Limits
 
-Analysis covers explicit method definitions, including private and endless methods.
-It does not execute Ruby or resolve runtime metaprogramming, `define_method`, aliases, generated accessors, or dynamic singleton receivers.
+Analysis covers explicit method definitions, including private and endless methods, and bare `define_method` calls with one literal symbol/string name and a block.
+Literal `define_method` names must be representable in UTF-8; unsupported names produce an error without replacing the previous snapshot.
+It does not execute Ruby or resolve other runtime metaprogramming, dynamic `define_method` names, calls with explicit receivers, aliases, generated accessors, or dynamic singleton receivers.
 Namespaces derived from expressions, such as `factory::Thing`, are skipped with their contents.
-Line coverage cannot distinguish expressions or methods sharing a source line, or separate evaluation of default parameters.
+Line coverage cannot distinguish expressions sharing a source line or separate evaluation of default parameters.
 Branch coverage is not used. Static namespace names do not reflect runtime constant reassignment.
 
+These counting and threshold rules change results from 0.1.x and require a minor release under the versioning policy. Regenerate coverage and snapshots and review existing limits when upgrading.
+
 ## Development
 
 ```sh
@@ -178,11 +203,14 @@ The implementation is tested on CRuby 3.3, 3.4, and 4.0. Other Ruby implementati
 
 ## Releases
 
+The [versioning policy](VERSIONING.md) defines the public interface, version changes, and deprecation rules.
+
 Signed `v*` tags trigger the release workflow. The tag must match `Crap4Ruby::VERSION`.
 Tests and the CRAP limit run before the gem is built. Publication requires approval in GitHub's `release` environment.
 RubyGems trusted publishing authenticates the workflow. Sigstore signs the built gem, and RubyGems stores its attestation.
 
 Report defects or ask questions through [GitHub issues](https://github.com/svyatov/crap4ruby/issues).
+Leonid Svyatov maintains this project. Security fixes target the latest release; see the [security policy](SECURITY.md).
 
 ## License
 

data/SECURITY.md

@@ -0,0 +1,15 @@
+# Security policy
+
+## Report a vulnerability
+
+Send private reports to [leonid@svyatov.com](mailto:leonid@svyatov.com). Do not disclose an unpatched vulnerability in a public issue.
+
+Include the affected crap4ruby and Ruby versions, a minimal reproduction, and the expected security impact.
+Remove credentials and private application data from examples.
+
+Leonid Svyatov monitors this address and will respond within 14 days.
+The response will confirm receipt and describe the next investigation step; it does not promise a fix within that period.
+
+## Supported versions
+
+Security fixes target the latest release. Reproduce the issue with that release when possible, but report suspected vulnerabilities in older releases too.

data/VERSIONING.md

@@ -0,0 +1,30 @@
+# Versioning policy
+
+crap4ruby uses [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) for its documented public interface.
+
+## Public interface
+
+The compatibility policy covers:
+
+- Documented CLI options, positional file selection, and exit codes.
+- Documented complexity, coverage, and CRAP scoring semantics.
+- The `.metrics/crap.edn` schema, including field meanings and value types.
+- The minimum supported Ruby version.
+
+Terminal table spacing, diagnostic wording, and Ruby classes are implementation details.
+YARD documents the Ruby interfaces for maintainers; those interfaces are outside this compatibility policy.
+Use the CLI and documented snapshot format when integrating with other tools.
+
+## Version changes
+
+During initial development (`0.y.z`), incompatible public changes increase MINOR. Compatible additions, fixes, and deprecations increase PATCH.
+Starting with `1.0.0`, incompatible public changes increase MAJOR, compatible additions and deprecations increase MINOR, and compatible fixes increase PATCH.
+
+Each release tag, gem version, and changelog entry must identify the same version. Published versions are never replaced.
+Documentation and CI maintenance alone do not require a release.
+
+## Deprecation
+
+Deprecate a public interface in a release before removing it in a later release.
+The notice must name its replacement or migration path and the earliest removal version, using a CLI diagnostic where applicable.
+Removal requires a later MINOR release during initial development or a later MAJOR release after `1.0.0`.