crap4ruby 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 55e5f45f41b35122c6ad4b4894e3d5e496af3842c4a4f28e8172806c45d8d620
-  data.tar.gz: '0279b34834aeba13649a0f124b6064b44a92fdffa868ad5f1a893e56a9067473'
+  metadata.gz: ef4ff5757bc98e35d4f9a59b34c2de273c8372b4b3019f0f1cd2234393900150
+  data.tar.gz: 7d05a4a6376b345e41ccaaba2311392e22608c4712ae61bae210a8ad392f540a
 SHA512:
-  metadata.gz: 555c402719177c91525c68611ee3e5e88ae0c674bf74a1f2b477857d4e97e017cfe50a2674d829e46a9fd7c16a252d69aaf97953ebb811d6a98a733596898157
-  data.tar.gz: 0e9ea5f5d64473c6547faaad0cc4126a0d7a1c0236c37c0a457cdb1e69ae5d828160619ddce843033df76c723c45440f64049b071a5bf74846ad11447700a1d4
+  metadata.gz: d0f0ae1b378c537b8eaac2972fa8bf866aeb3b0771fe0e66062b7e51309e2d08ae45c91a697ed948f5cb2e3837b2d0d7c21064c2fbf3542c9a764a1295bed790
+  data.tar.gz: b9454920d722a74389ae717afaa0cf01205b16ba08aeea24a814161ebf3b519ad2388d2b82a2a78bb9e8b244b723f5f8fcfd8c7198b9e0c55bb4e93564a7c5e3

data/CHANGELOG.md

@@ -1,7 +1,17 @@
 # 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.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 +26,6 @@
 
 - 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.1.1...HEAD
+[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,44 @@
 # 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 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 runs Steep, requires 100% typed calls across every Ruby file, runs tests with fresh SimpleCov coverage, and validates YARD documentation.
+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 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 +46,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.1.1.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
@@ -104,7 +115,7 @@ Every successful analysis replaces the snapshot, including filtered analyses and
 
 ## 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
@@ -178,11 +189,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`.

data/lib/crap4ruby/analyzer.rb

@@ -1,7 +1,16 @@
 # frozen_string_literal: true
 
 module Crap4Ruby
+  # Finds explicit Ruby method definitions without executing source code.
   class Analyzer
+    # Analyzes method bodies and parameter defaults with Prism.
+    #
+    # @param source [String] Ruby source text
+    # @param path [String] source label used in results and parse errors
+    # @return [Array<MethodInfo>] methods in traversal order, including nested definitions
+    # @raise [Error] if source cannot be parsed
+    # @example Analyze a method without loading it
+    #   Analyzer.new.call("def eligible?(age) = age >= 18", path: "person.rb")
     def call(source, path:)
       result = Prism.parse(source)
       unless result.success?
@@ -13,6 +22,13 @@ module Crap4Ruby
 
     private
 
+    # Tracks lexical owners; skips owners that cannot be resolved statically.
+    #
+    # @param node [Prism::Node, nil] subtree to visit
+    # @param scope [Array<String>] lexical namespace components
+    # @param singleton [Boolean] whether definitions belong to a singleton class
+    # @param path [String] source label
+    # @return [Array<MethodInfo>] discovered method definitions
     def discover(node, scope, singleton, path)
       return [] unless node
 
@@ -30,6 +46,13 @@ module Crap4Ruby
       end
     end
 
+    # Measures a definition independently from definitions nested within it.
+    #
+    # @param node [Prism::DefNode] method definition
+    # @param scope [Array<String>] lexical namespace components
+    # @param singleton [Boolean] whether the enclosing scope is a singleton class
+    # @param path [String] source label
+    # @return [Array<MethodInfo>] this method and its nested definitions
     def discover_method(node, scope, singleton, path)
       owner = node.receiver && !node.receiver.is_a?(Prism::SelfNode) ? qualify(node.receiver, scope) : scope
       return [] unless owner
@@ -41,6 +64,13 @@ module Crap4Ruby
         discover(node.body, scope, singleton, path)
     end
 
+    # Resolves constant syntax without looking up runtime constants.
+    # Declarations append names; references can reuse a lexical ancestor.
+    #
+    # @param node [Prism::Node, nil] namespace expression
+    # @param scope [Array<String>] lexical namespace components
+    # @param declaration [Boolean] whether the expression declares a namespace
+    # @return [Array<String>, nil] qualified components, or nil for dynamic expressions
     def qualify(node, scope, declaration: false)
       case node
       when Prism::ParenthesesNode
@@ -50,10 +80,16 @@ module Crap4Ruby
         ancestor = scope.rindex(name) unless declaration
         ancestor ? scope.take(ancestor + 1) : scope + [name]
       when Prism::ConstantPathNode
-        (node.parent ? qualify(node.parent, scope) : [])&.+([node.name.to_s])
+        # @type var parent: Array[String]?
+        parent = node.parent ? qualify(node.parent, scope) : []
+        parent&.+([node.name.to_s])
       end
     end
 
+    # Counts branch operations, including safe navigation, outside nested definitions.
+    #
+    # @param node [Prism::Node, nil] subtree to measure
+    # @return [Integer] number of decisions, excluding the method's base complexity
     def decisions(node)
       return 0 unless node
       return 0 if boundary?(node)
@@ -62,7 +98,12 @@ module Crap4Ruby
         :when_node, :in_node, :rescue_node, :rescue_modifier_node, :and_node, :or_node].include?(node.type) ||
         node.type.to_s.match?(/_(?:and|or)_write_node\z/)
       count = decision ? 1 : 0
-      count += 1 if node.respond_to?(:safe_navigation?) && node.safe_navigation?
+      case node
+      when Prism::CallNode, Prism::CallAndWriteNode, Prism::CallOrWriteNode,
+          Prism::CallOperatorWriteNode, Prism::CallTargetNode, Prism::IndexAndWriteNode,
+          Prism::IndexOrWriteNode, Prism::IndexOperatorWriteNode, Prism::IndexTargetNode
+        count += 1 if node.safe_navigation?
+      end
       count + node.compact_child_nodes.sum { |child| decisions(child) }
     end
 
@@ -70,11 +111,15 @@ module Crap4Ruby
       [Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::SingletonClassNode].any? { |type| node.is_a?(type) }
     end
 
+    # Selects body lines without nested methods, classes, or modules.
+    #
+    # @param node [Prism::Node, nil] method body
+    # @return [Array<Integer>] one-based source lines; empty for an absent body
     def body_lines(node)
       return [] unless node
 
       lines = (node.location.start_line..node.location.end_line).to_a
-      excluded = []
+      excluded = [] #: Array[Integer]
       collect_boundaries(node, excluded)
       lines - excluded
     end

data/lib/crap4ruby/cli.rb

@@ -3,12 +3,25 @@
 require "optparse"
 
 module Crap4Ruby
+  # Coordinates file discovery, coverage, scoring, and CLI output.
   class CLI
+    # Sets output destinations without running an analysis.
+    #
+    # @param stdout [#puts, #write] destination for reports, help, and version output
+    # @param stderr [#puts, #write] destination for diagnostics and coverage command output
     def initialize(stdout: $stdout, stderr: $stderr)
       @stdout = stdout
       @stderr = stderr
     end
 
+    # Runs the requested analysis and replaces the snapshot after successful scoring.
+    # Help and version requests produce output without writing a snapshot.
+    # Expected usage, input, filesystem, and command errors are printed to stderr.
+    #
+    # @param arguments [Array<String>] command-line tokens; option parsing mutates this array
+    # @return [Integer] 0 on success, 1 on a handled error, or 2 when a score exceeds the threshold
+    # @example Analyze complexity without coverage
+    #   CLI.new.run(["--no-coverage", "--source-root", "lib"])
     def run(arguments)
       options, parser, paths = parse_options(arguments)
       return @stdout.puts(parser) || 0 if options[:help]
@@ -35,18 +48,37 @@ module Crap4Ruby
 
     private
 
+    # Removes parsed options from arguments and returns the remaining path selectors.
+    #
+    # @param arguments [Array<String>] mutable command-line tokens
+    # @return [Array(Hash, OptionParser, Array<String>)] options, parser, and remaining selectors
+    # @raise [OptionParser::ParseError] if an option or threshold is invalid
     def parse_options(arguments)
+      # @type var options: options
       options = {root: Dir.pwd, source_roots: [], changed: false, coverage: "coverage/.resultset.json"}
       parser = OptionParser.new do |cli|
         cli.banner = "Usage: crap4ruby [options] [file-or-directory-or-filter ...]"
-        cli.on("--root PATH", "Project root (default: current directory)") { |path| options[:root] = path }
-        cli.on("--source-root PATH", "Analyze this directory; repeat for multiple roots") { |path| options[:source_roots] << path }
+        cli.on("--root PATH", "Project root (default: current directory)") do |path|
+          # @type var path: String
+          options[:root] = path
+        end
+        cli.on("--source-root PATH", "Analyze this directory; repeat for multiple roots") do |path|
+          # @type var path: String
+          options[:source_roots] << path
+        end
         cli.on("--changed", "Analyze Git additions and edits, including untracked files") { options[:changed] = true }
-        cli.on("--coverage PATH", "SimpleCov resultset (default: coverage/.resultset.json)") { |path| options[:coverage] = path }
+        cli.on("--coverage PATH", "SimpleCov resultset (default: coverage/.resultset.json)") do |path|
+          # @type var path: String
+          options[:coverage] = path
+        end
         cli.on("--no-coverage", "Complexity only; coverage and CRAP are N/A") { options[:no_coverage] = true }
         cli.on("--use-existing-coverage", "Read reports without running tests (the default)") { options[:existing] = true }
-        cli.on("--coverage-command COMMAND", "Run a shell command that refreshes the resultset") { |command| options[:command] = command }
+        cli.on("--coverage-command COMMAND", "Run a shell command that refreshes the resultset") do |command|
+          # @type var command: String
+          options[:command] = command
+        end
         cli.on("--threshold NUMBER", "Exit 2 when CRAP exceeds this value") do |value|
+          # @type var value: String
           number = Float(value)
           raise OptionParser::InvalidArgument, "threshold must be finite and nonnegative" unless number.finite? && number >= 0
 
@@ -60,12 +92,22 @@ module Crap4Ruby
       [options, parser, parser.parse(arguments)]
     end
 
+    # Rejects a coverage command when coverage is disabled or explicitly read-only.
+    #
+    # @param options [Hash] parsed CLI options
+    # @return [void]
+    # @raise [Error] if coverage options conflict
     def validate_options(options)
       if options[:command] && (options[:no_coverage] || options[:existing])
         raise Error, "--coverage-command cannot be combined with --no-coverage or --use-existing-coverage"
       end
     end
 
+    # Compares unrounded, known CRAP scores with a strict upper limit.
+    #
+    # @param entries [Array<Entry>] scored methods
+    # @param threshold [Float, nil] maximum allowed score, or nil to disable the check
+    # @return [Integer] 2 after reporting a violation to stderr, otherwise 0
     def threshold_status(entries, threshold)
       if threshold && entries.any? { |entry| entry.crap && entry.crap > threshold }
         @stderr.puts("CRAP threshold exceeded: #{threshold}")
@@ -81,6 +123,15 @@ module Crap4Ruby
       Coverage.load(report, root: root)
     end
 
+    # Runs a shell command at root and forwards its combined output to stderr.
+    # Requires success and a changed report stamp before coverage can be consumed.
+    #
+    # @param command [String] command passed to `sh -c` with the caller's environment
+    # @param root [String] command working directory
+    # @param report [String] expected coverage report path
+    # @return [void]
+    # @raise [Error] if the command is empty, fails, or leaves the report stamp unchanged
+    # @raise [SystemCallError] if the command cannot start or report metadata cannot be read
     def run_coverage(command, root, report)
       raise Error, "--coverage-command must not be empty" if command.strip.empty?
 
@@ -94,6 +145,11 @@ module Crap4Ruby
       raise Error, "coverage command did not refresh #{report}" if report_stamp(report) == before
     end
 
+    # Captures metadata used to detect a newly generated or refreshed report.
+    #
+    # @param path [String] coverage report path
+    # @return [Array(Integer, Time, Time, Integer), nil] inode, modification time,
+    #   change time, and size; nil if the path does not exist
     def report_stamp(path)
       stat = File.stat(path)
       [stat.ino, stat.mtime, stat.ctime, stat.size]

data/lib/crap4ruby/coverage.rb

@@ -3,7 +3,14 @@
 require "json"
 
 module Crap4Ruby
+  # Merges SimpleCov line coverage across named test suites.
   class Coverage
+    # Reads a SimpleCov resultset, accepting legacy arrays and line-coverage objects.
+    #
+    # @param path [String] JSON resultset path, relative to the working directory or absolute
+    # @param root [String] base directory for source paths inside the report
+    # @return [Coverage] merged coverage
+    # @raise [Error] if the report cannot be read, parsed, or validated
     def self.load(path, root:)
       new(JSON.parse(File.read(path)), root: root)
     rescue SystemCallError => error
@@ -12,6 +19,11 @@ module Crap4Ruby
       raise Error, "#{path}: invalid SimpleCov report (#{error.message})"
     end
 
+    # Validates and merges suite reports by the maximum hit count for each line.
+    #
+    # @param suites [Hash{String => Hash}] parsed resultset keyed by suite name
+    # @param root [String] base directory for relative source paths
+    # @raise [Error] if suites or line coverage are malformed
     def initialize(suites, root:)
       raise Error, "expected named test suites" unless suites.is_a?(Hash) && !suites.empty?
 
@@ -19,9 +31,16 @@ module Crap4Ruby
       suites.each_value { |suite| add_suite(suite, root) }
     end
 
+    # Measures executable body lines with positive hit counts.
+    # Null and out-of-range lines do not enter the denominator.
+    #
+    # @param method [MethodInfo] method whose path and body lines select coverage
+    # @return [Float, nil] fraction from 0 to 1; zero for an absent file,
+    #   or nil when a reported file has no measurable body lines
     def fraction(method)
       path = File.expand_path(method.path)
       path = File.realpath(path) if File.exist?(path)
+      # @type var lines: Array[Integer?]?
       lines = @files[path]
       return 0.0 unless lines
 
@@ -40,6 +59,13 @@ module Crap4Ruby
       suite["coverage"].each { |path, data| add_file(path, data, root) }
     end
 
+    # Normalizes a source path and merges line counts across suites.
+    #
+    # @param path [String] source path from a suite report
+    # @param data [Array<Integer, nil>, Hash] legacy counts or an object with a `lines` array
+    # @param root [String] base directory for relative source paths
+    # @return [void]
+    # @raise [Error] if line counts are invalid
     def add_file(path, data, root)
       key = File.expand_path(path, root)
       key = File.realpath(key) if File.exist?(key)
@@ -47,6 +73,8 @@ module Crap4Ruby
       unless lines.is_a?(Array) && lines.all? { |hit| hit.nil? || (hit.is_a?(Integer) && hit >= 0) }
         raise Error, "#{path}: expected nonnegative line counts or null"
       end
+      # Every element was validated above; Steep cannot narrow an array through all?.
+      lines = lines #: Array[Integer?]
       previous = @files[key] || []
       @files[key] = Array.new([previous.size, lines.size].max) do |index|
         [previous[index], lines[index]].compact.max

data/lib/crap4ruby/discovery.rb

@@ -4,9 +4,22 @@ require "find"
 require "open3"
 
 module Crap4Ruby
+  # Selects Ruby source files from explicit paths, directories, and Git changes.
   module Discovery
+    # Directory names excluded during recursive traversal.
     EXCLUDED = %w[test tests spec features vendor node_modules target coverage tmp log pkg build dist].freeze
 
+    # Combines source roots and existing paths, then applies filters and Git selection.
+    # Explicit files bypass traversal exclusions but must have the `.rb` extension.
+    # Defaults to the project root when no source roots or existing paths are given.
+    #
+    # @param root [String] absolute project directory
+    # @param source_roots [Array<String>] source directories, absolute or relative to root
+    # @param paths [Array<String>] existing paths or substring filters relative to root
+    # @param changed [Boolean] restrict results to staged, unstaged, and untracked files
+    # @return [Array<String>] sorted, unique real paths; substring filters use OR
+    # @raise [Error] if a source root is not a directory or Git fails
+    # @raise [SystemCallError] if paths cannot be read or resolved
     def self.call(root:, source_roots:, paths:, changed:)
       existing, filters = paths.partition { |path| File.exist?(File.expand_path(path, root)) }
       roots = source_roots.map do |path|
@@ -24,8 +37,14 @@ module Crap4Ruby
       files
     end
 
+    # Walks a directory without following symlinks or entering excluded directories.
+    # Hidden files and test/spec filenames are excluded; extensions are not filtered.
+    #
+    # @param root [String] directory to traverse, including an explicitly selected hidden directory
+    # @return [Array<String>] candidate file paths in traversal order
+    # @raise [SystemCallError] if traversal fails
     def self.walk(root)
-      paths = []
+      paths = [] #: Array[String]
       Find.find(root) do |path|
         name = File.basename(path)
         if File.directory?(path)
@@ -37,6 +56,13 @@ module Crap4Ruby
       paths
     end
 
+    # Runs Git in the project directory without a shell.
+    #
+    # @param root [String] working directory for Git
+    # @param arguments [Array<String>] command and arguments
+    # @return [String] standard output, preserving NUL separators
+    # @raise [Error] if Git exits unsuccessfully
+    # @raise [SystemCallError] if Git cannot be started
     def self.git(root, *arguments)
       output, error, status = Open3.capture3("git", "-C", root, *arguments)
       raise Error, "git: #{error.strip}" unless status.success?
@@ -44,11 +70,18 @@ module Crap4Ruby
       output
     end
 
+    # Finds existing staged, unstaged, and untracked files under the project directory.
+    # Deleted files are omitted and renames are treated as deletion and addition.
+    #
+    # @param root [String] directory inside a Git working tree
+    # @return [Array<String>] real paths, without extension or traversal filtering
+    # @raise [Error] if Git cannot inspect the working tree
+    # @raise [SystemCallError] if Git cannot start or a path cannot be resolved
     def self.changed_files(root)
       top = git(root, "rev-parse", "--show-toplevel").chomp
       git(root, "status", "--porcelain=v1", "-z", "--no-renames", "--untracked-files=all", "--", ".")
         .split("\0").filter_map do |entry|
-          path = File.join(top, entry[3..])
+          path = File.join(top, entry[3..].to_s)
           File.realpath(path) if File.file?(path)
         end
     end

data/lib/crap4ruby/report.rb

@@ -4,11 +4,21 @@ require "fileutils"
 require "tempfile"
 
 module Crap4Ruby
+  # Formats analysis results and atomically replaces the project snapshot.
   module Report
+    # Ranks known scores first, from highest to lowest.
+    # Ties use namespace, method name, then source path in ascending order.
+    #
+    # @param entries [Array<Entry>] unsorted results
+    # @return [Array<Entry>] new sorted array, without modifying the input
     def self.sorted(entries)
       entries.sort_by { |entry| [entry.crap ? 0 : 1, -(entry.crap || 0), entry.namespace, entry.name, entry.path] }
     end
 
+    # Formats a terminal table, preserving entry order and displaying unknown values as N/A.
+    #
+    # @param entries [Array<Entry>] results in display order
+    # @return [String] table with one decimal place for percentages and scores, ending with a newline
     def self.table(entries)
       rows = [["Function", "Namespace", "CC", "Cov%", "CRAP"]] + entries.map do |entry|
         [entry.name, entry.namespace, entry.complexity.to_s,
@@ -23,6 +33,11 @@ module Crap4Ruby
       (["CRAP Report", "==========="] + lines).join("\n") + "\n"
     end
 
+    # Serializes the crapper-compatible snapshot, preserving entry order.
+    # Source paths are omitted; unknown numeric values become EDN nil.
+    #
+    # @param entries [Array<Entry>] results in snapshot order
+    # @return [String] EDN map containing entries, ending with a newline
     def self.edn(entries)
       rows = entries.map do |entry|
         "  {:name #{JSON.generate(entry.name)}, :namespace #{JSON.generate(entry.namespace)}, " \
@@ -31,6 +46,10 @@ module Crap4Ruby
       rows.empty? ? "{:entries []}\n" : "{:entries [\n#{rows.join("\n")}\n]}\n"
     end
 
+    # Formats an EDN number with at most four decimal places and at least one.
+    #
+    # @param value [Float, nil] percentage or CRAP score
+    # @return [String] decimal representation, or `nil` for an unknown value
     def self.number(value)
       return "nil" if value.nil?
 
@@ -38,6 +57,13 @@ module Crap4Ruby
       text.end_with?(".") ? "#{text}0" : text
     end
 
+    # Atomically replaces `.metrics/crap.edn`, creating the directory if necessary.
+    # An empty selection replaces the snapshot with an empty entries vector.
+    #
+    # @param entries [Array<Entry>] results in snapshot order
+    # @param root [String] project directory that receives the snapshot
+    # @return [String] snapshot path
+    # @raise [SystemCallError, IOError] if the snapshot cannot be written or replaced
     def self.write(entries, root:)
       directory = File.join(root, ".metrics")
       FileUtils.mkdir_p(directory)

data/lib/crap4ruby/score.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
 
 module Crap4Ruby
+  # Combines static complexity and measured coverage into CRAP scores.
   module Score
+    # Calculates `complexity**2 * (1 - fraction)**3 + complexity`.
+    #
+    # @param method [MethodInfo] static method analysis
+    # @param coverage [Coverage, nil] coverage reader, or nil to disable scoring
+    # @return [Entry] result with percentage coverage; coverage and CRAP are nil
+    #   when coverage is disabled or the method has no measurable lines
     def self.call(method, coverage)
       fraction = coverage&.fraction(method)
-      crap = method.complexity**2 * (1 - fraction)**3 + method.complexity if fraction
+      crap = method.complexity * method.complexity * (1 - fraction)**3 + method.complexity if fraction
       Entry.new(method.name, method.namespace, method.complexity, fraction && fraction * 100, crap, method.path)
     end
   end

data/lib/crap4ruby/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module Crap4Ruby
-  VERSION = "0.1.0"
+  # Gem version used by the CLI and release process.
+  VERSION = "0.1.1"
 end

data/lib/crap4ruby.rb

@@ -3,10 +3,48 @@
 require "prism"
 require_relative "crap4ruby/version"
 
+# Static method analysis, coverage, and CRAP reporting for the CLI.
+# These Ruby interfaces are maintainer APIs, outside the compatibility policy.
+#
+# @api private
 module Crap4Ruby
-  Error = Class.new(StandardError)
+  # Invalid source, coverage, command options, or external command results.
+  class Error < StandardError
+  end
+
+  # Immutable static analysis of one explicit method definition.
   MethodInfo = Data.define(:name, :namespace, :complexity, :lines, :path)
+
+  # Immutable analysis result with coverage and a CRAP score.
   Entry = Data.define(:name, :namespace, :complexity, :coverage, :crap, :path)
+
+  # @!parse
+  #   class Crap4Ruby::MethodInfo
+  #     # @return [String] method name, prefixed with `self.` for singleton methods
+  #     attr_reader :name
+  #     # @return [String] lexical owner, or `Object` for a top-level method
+  #     attr_reader :namespace
+  #     # @return [Integer] cyclomatic complexity, including parameter defaults
+  #     attr_reader :complexity
+  #     # @return [Array<Integer>] one-based body lines, excluding nested definitions
+  #     attr_reader :lines
+  #     # @return [String] source path supplied to the analyzer
+  #     attr_reader :path
+  #   end
+  #   class Crap4Ruby::Entry
+  #     # @return [String] method name, prefixed with `self.` for singleton methods
+  #     attr_reader :name
+  #     # @return [String] lexical owner, or `Object` for a top-level method
+  #     attr_reader :namespace
+  #     # @return [Integer] cyclomatic complexity
+  #     attr_reader :complexity
+  #     # @return [Float, nil] percentage from 0 to 100, or nil when unmeasurable or disabled
+  #     attr_reader :coverage
+  #     # @return [Float, nil] CRAP score, or nil when coverage is unknown
+  #     attr_reader :crap
+  #     # @return [String] source path supplied to the analyzer
+  #     attr_reader :path
+  #   end
 end
 
 require_relative "crap4ruby/analyzer"

data/sig/crap4ruby.rbs

@@ -0,0 +1,96 @@
+module Crap4Ruby
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class MethodInfo < Data
+    attr_reader name: String
+    attr_reader namespace: String
+    attr_reader complexity: Integer
+    attr_reader lines: Array[Integer]
+    attr_reader path: String
+    def self.new: (String name, String namespace, Integer complexity, Array[Integer] lines, String path) -> instance
+                | (name: String, namespace: String, complexity: Integer, lines: Array[Integer], path: String) -> instance
+    alias self.[] self.new
+    def with: (?name: String, ?namespace: String, ?complexity: Integer, ?lines: Array[Integer], ?path: String) -> instance
+  end
+
+  class Entry < Data
+    attr_reader name: String
+    attr_reader namespace: String
+    attr_reader complexity: Integer
+    attr_reader coverage: Float?
+    attr_reader crap: Float?
+    attr_reader path: String
+    def self.new: (String name, String namespace, Integer complexity, Float? coverage, Float? crap, String path) -> instance
+                | (name: String, namespace: String, complexity: Integer, coverage: Float?, crap: Float?, path: String) -> instance
+    alias self.[] self.new
+    def with: (?name: String, ?namespace: String, ?complexity: Integer, ?coverage: Float?, ?crap: Float?, ?path: String) -> instance
+  end
+
+  class Analyzer
+    def call: (String source, path: String) -> Array[MethodInfo]
+    private
+    def discover: (Prism::Node? node, Array[String] scope, bool singleton, String path) -> Array[MethodInfo]
+    def discover_method: (Prism::DefNode node, Array[String] scope, bool singleton, String path) -> Array[MethodInfo]
+    def qualify: (Prism::Node? node, Array[String] scope, ?declaration: bool) -> Array[String]?
+    def decisions: (Prism::Node? node) -> Integer
+    def boundary?: (Prism::Node node) -> bool
+    def body_lines: (Prism::Node? node) -> Array[Integer]
+    def collect_boundaries: (Prism::Node node, Array[Integer] excluded) -> void
+  end
+
+  type json = nil | bool | Integer | Float | String | Array[json] | Hash[String, json]
+
+  class Coverage
+    @files: Hash[String, Array[Integer?]]
+    def self.load: (String path, root: String) -> Coverage
+    def initialize: (json suites, root: String) -> void
+    def fraction: (MethodInfo method) -> Float?
+    private
+    def add_suite: (json suite, String root) -> void
+    def add_file: (String path, json data, String root) -> void
+  end
+
+  module Discovery
+    EXCLUDED: Array[String]
+    def self.call: (root: String, source_roots: Array[String], paths: Array[String], changed: bool) -> Array[String]
+    def self.walk: (String root) -> Array[String]
+    def self.git: (String root, *String arguments) -> String
+    def self.changed_files: (String root) -> Array[String]
+  end
+
+  module Score
+    def self.call: (MethodInfo method, Coverage? coverage) -> Entry
+  end
+
+  module Report
+    def self.sorted: (Array[Entry] entries) -> Array[Entry]
+    def self.table: (Array[Entry] entries) -> String
+    def self.edn: (Array[Entry] entries) -> String
+    def self.number: (Float? value) -> String
+    def self.write: (Array[Entry] entries, root: String) -> String
+  end
+
+  interface _Output
+    def puts: (*String | OptionParser objects) -> nil
+    def write: (String text) -> Integer
+  end
+
+  class CLI
+    type options = { root: String, source_roots: Array[String], changed: bool, coverage: String,
+      ?help: bool, ?version: bool, ?no_coverage: bool, ?existing: bool, ?command: String, ?threshold: Float }
+    @stdout: _Output
+    @stderr: _Output
+    def initialize: (?stdout: _Output, ?stderr: _Output) -> void
+    def run: (Array[String] arguments) -> Integer
+    private
+    def parse_options: (Array[String] arguments) -> [options, OptionParser, Array[String]]
+    def validate_options: (options options) -> void
+    def threshold_status: (Array[Entry] entries, Float? threshold) -> Integer
+    def load_coverage: (options options, String root) -> Coverage
+    def run_coverage: (String command, String root, String report) -> void
+    def report_stamp: (String path) -> [Integer, Time, Time, Integer]?
+  end
+end

data/sig/manifest.yaml

@@ -0,0 +1,8 @@
+dependencies:
+  - name: prism
+  - name: json
+  - name: optparse
+  - name: find
+  - name: open3
+  - name: fileutils
+  - name: tempfile

data/sig/stdlib.rbs

@@ -0,0 +1,10 @@
+# Complete the stdlib signatures for the subprocess options used here.
+module Open3
+  def self.popen2e: [T] (*String command, chdir: String) { (IO input, IO output, Process::Waiter process) -> T } -> T
+  def self.capture3: (*String command, chdir: String) -> [String, String, Process::Status]
+                  | ...
+end
+
+class Process::Waiter
+  def value: () -> Process::Status
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: crap4ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Leonid Svyatov
@@ -37,9 +37,12 @@ extensions: []
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
+- CODE_OF_CONDUCT.md
 - CONTRIBUTING.md
 - LICENSE
 - README.md
+- SECURITY.md
+- VERSIONING.md
 - exe/crap4ruby
 - lib/crap4ruby.rb
 - lib/crap4ruby/analyzer.rb
@@ -49,10 +52,14 @@ files:
 - lib/crap4ruby/report.rb
 - lib/crap4ruby/score.rb
 - lib/crap4ruby/version.rb
+- sig/crap4ruby.rbs
+- sig/manifest.yaml
+- sig/stdlib.rbs
 homepage: https://github.com/svyatov/crap4ruby
 licenses:
 - MIT
 metadata:
+  documentation_uri: https://www.rubydoc.info/gems/crap4ruby
   source_code_uri: https://github.com/svyatov/crap4ruby
   bug_tracker_uri: https://github.com/svyatov/crap4ruby/issues
   changelog_uri: https://github.com/svyatov/crap4ruby/blob/main/CHANGELOG.md