snoot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2a358948bce28c9ff2446d748bbf7a387946f93acf7f332ec25eecc63a0f4700
+  data.tar.gz: 0f11f20fe357b26d27fb29459188c958d5804ae64e86ffee6b112a584b28fd87
+SHA512:
+  metadata.gz: 66266a46163b0b322ee44e2ad384fa1b3b44bd5e26c42bb3770cf0d2657dac72ef0da51deb1282d1367ffacfbd50bb1afa279ac2bbdbcab43a4b617d51918530
+  data.tar.gz: 734c2edb2cbe119d6588e751e1ac1c2a9de4190b4ab2929412dbf584f6abeb2fa0c3f9b01ce632bdff71bb0a1094c29d9fac15948ff7845f959b0cc889dfb678

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-14
+
+### Added
+
+- Initial release.
+- `snoot` CLI that orchestrates reek, flog, and flay over a given path
+  set (or the current directory when no paths are given) and emits a
+  single agent-targeted finding to stdout.
+
+[Unreleased]: https://github.com/bkudria/snoot/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/bkudria/snoot/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Kudria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# snoot
+
+A Ruby gem that orchestrates `reek`, `flog`, and `flay` over a configured path set and emits a single agent-targeted report describing one finding.
+
+The report is centred on an LLM coding agent as the reader: each run produces one of two report shapes -- a doc + instances pair for smell findings, or a header + finding context + doc trio for complexity and duplication findings -- or acknowledges that nothing was worth reporting, or signals analyser failure.
+
+## Status
+
+Pre-1.0. Three analysers (Reek / Flog / Flay) are used, and `snoot <paths>` drives the full pipeline end-to-end: it reports a single finding to stdout, an acknowledgement when nothing is worth reporting, or a failure line on stderr. With no positional arguments, `snoot` scans the current directory. The exit code is `1` when a finding is rendered, `0` when there is nothing to report, and `2` when analysis fails.
+
+## Specification
+
+The behaviour is specified in [`snoot.allium`](snoot.allium) (the Allium
+behavioural contract); [`GOALS.md`](GOALS.md) records the design rationale.
+The spec, the implementation in `lib/`, and the tests in `spec/` are peer
+artifacts and are kept in sync — see [`CLAUDE.md`](CLAUDE.md).
+
+## Installation
+
+Requires Ruby 4.0 or later.
+
+    gem install snoot
+
+## Usage
+
+After install, the `snoot` executable is available on PATH:
+
+    snoot --version
+    snoot --help
+    snoot lib/foo.rb            # analyse a specific path
+    snoot                       # scan the current directory
+
+`snoot` emits a single agent-targeted finding to stdout and exits with:
+
+- `0` — nothing worth reporting,
+- `1` — a finding was rendered,
+- `2` — analysis failed (failure line on stderr).
+
+## Privacy
+
+`snoot` runs entirely locally. It analyses source on disk with the bundled
+`reek`, `flog`, and `flay` libraries and writes its single finding to stdout —
+no source code, findings, or telemetry are sent over the network.
+
+## License
+
+snoot is MIT-licensed; see [`LICENSE`](LICENSE).
+
+The reek smell-documentation files vendored under [`data/reek_docs/`](data/reek_docs/) are reproduced from [troessner/reek](https://github.com/troessner/reek) (Copyright © 2008, 2009 Kevin Rutherford) under the MIT license; see [`data/reek_docs/LICENSE`](data/reek_docs/LICENSE). Re-syncing those files with `rake docs:sync` also refreshes the bundled license notice.

data/data/reek_docs/API.md

@@ -0,0 +1,174 @@
+# Using Reek inside your Ruby application
+
+## Installation
+
+Either standalone via
+
+```bash
+gem install reek
+```
+
+or by adding
+
+```
+gem 'reek'
+```
+
+to your Gemfile.
+
+## Quick start
+
+Code says more than a thousand words:
+
+```ruby
+require 'reek'
+
+source = <<-RUBY
+  class Dirty
+    def m(a,b,c)
+      puts a,b
+    end
+  end
+RUBY
+
+reporter = Reek::Report::TextReport.new
+examiner = Reek::Examiner.new source
+reporter.add_examiner examiner
+reporter.show
+```
+
+This would output the following on STDOUT:
+
+```
+string -- 5 warnings:
+  Dirty has no descriptive comment (IrresponsibleModule)
+  Dirty#m has the name 'm' (UncommunicativeMethodName)
+  Dirty#m has the parameter name 'a' (UncommunicativeParameterName)
+  Dirty#m has the parameter name 'b' (UncommunicativeParameterName)
+  Dirty#m has unused parameter 'c' (UnusedParameters)
+```
+
+Note that `Reek::Examiner.new` can take `source` as `String`, `Pathname`, `File` or `IO`.
+
+## API stability
+
+Everything that is mentioned in this document can be considered stable in the
+sense that it will only change across major versions.
+
+There is one thing in this API documentation you can't and shouldn't rely on:
+The `SmellWarning` messages itself.
+
+Something like this
+
+```
+Dirty#m has the parameter name 'a' (UncommunicativeParameterName)
+```
+
+might change even across minor versions.
+
+You should not need to be specific about those messages anyways.
+In case you'd like to be specific about `SmellWarnings` please have a look at
+[accessing the smell warnings directly](#accessing-the-smell-warnings-directly).
+
+Additionally you can use one of our structured [outputs formats](#choosing-your-output-format)
+like JSON or YAML if you need a more fine-grained access to our
+`SmellWarnings`.
+
+## Choosing your output format
+
+Besides normal text output, Reek can generate output in YAML,
+JSON, HTML and XML by using the following Report types:
+
+```
+TextReport
+YAMLReport
+JSONReport
+HTMLReport
+XMLReport
+```
+
+## Configuration
+
+Given you have the following configuration file called `.reek.yml` in your root directory:
+
+```yaml
+---
+IrresponsibleModule:
+  enabled: false
+```
+
+Reek will load this file automatically by default. If you want to load the
+configuration explicitly, you can use one of the methods below.
+
+You can now use either
+
+```ruby
+Reek::Configuration::AppConfiguration.from_path Pathname.new('config.reek')
+```
+
+but you can also pass a hash with the contents of the `.reek.yml` YAML file
+to `Reek::Configuration::AppConfiguration.from_hash`.
+
+Given the example above you would load that as follows:
+
+```ruby
+require 'reek'
+
+config_hash = { 'IrresponsibleModule' => { 'enabled' => false } }
+configuration = Reek::Configuration::AppConfiguration.from_hash config_hash
+
+source = <<-RUBY
+  class Dirty
+    def call_me(a,b)
+      puts a,b
+    end
+  end
+RUBY
+
+reporter = Reek::Report::TextReport.new
+examiner = Reek::Examiner.new(source, configuration: configuration); nil
+reporter.add_examiner examiner; nil
+reporter.show
+```
+
+This would now only report `UncommunicativeParameterName` but not
+`IrresponsibleModule` for the `Dirty` class:
+
+```
+string -- 2 warnings:
+  Dirty#call_me has the parameter name 'a' (UncommunicativeParameterName)
+  Dirty#call_me has the parameter name 'b' (UncommunicativeParameterName)
+```
+
+Of course, directory specific configuration and excluded paths are supported as
+well:
+
+```
+config_hash = {
+  'IrresponsibleModule' => { 'enabled' => false }
+  'spec/samples/three_clean_files/' =>
+    { 'UtilityFunction' => { "enabled" => false } }
+  'exclude_paths' =>
+    [ 'spec/samples/two_smelly_files' ]
+}
+```
+
+## Accessing the smell warnings directly
+
+You can also access the smells detected by an examiner directly:
+
+```ruby
+require 'reek'
+
+source = <<-END
+  class C
+  end
+END
+
+examiner = Reek::Examiner.new source
+examiner.smells.each do |smell|
+  puts smell.message
+end
+```
+
+`Examiner#smells` returns a list of `SmellWarning` objects.

data/data/reek_docs/Attribute.md

@@ -0,0 +1,39 @@
+# Attribute
+
+## Introduction
+
+A class that publishes a setter for an instance variable invites
+client classes to become too intimate with its inner workings, and in
+particular with its representation of state.
+
+The same holds to a lesser extent for getters, but Reek doesn't flag those.
+
+## Example
+
+Given:
+
+```ruby
+class Klass
+  attr_accessor :dummy
+end
+```
+
+Reek would emit the following warning:
+
+```
+reek test.rb
+
+test.rb -- 1 warning:
+  [2]:Attribute: Klass#dummy is a writable attribute
+```
+
+## Support in Reek
+
+This detector raises a warning for every public `attr_writer`,
+`attr_accessor`, and `attr` with the writable flag set to `true`.
+
+Reek does not raise warnings for read-only attributes.
+
+## Configuration
+
+_Attribute_ supports only the [Basic Smell Options](Basic-Smell-Options.md).

data/data/reek_docs/Basic-Smell-Options.md

@@ -0,0 +1,85 @@
+# Basic Smell Options
+
+## Introduction
+
+Every smell detector in Reek offers at least the following configuration options:
+
+| Option         | Value       | Effect  |
+| ---------------|-------------|---------|
+| `enabled` |  Boolean | Determines whether the smell detector is active. Defaults to `true` |
+| `exclude` | an array of strings that will be converted into regular expressions | Ignores any context whose full description matches any element of this array. |
+
+The file `docs/defaults.reek.yml` (shipped with the Reek gem) lists any default
+exclusions for each smell.
+
+## Examples
+
+**An easy one:**
+
+To stop Reek reporting smells in any method called `write` you might create a configuration file containing this:
+
+```yaml
+DuplicateMethodCall:
+  exclude:
+  - write
+```
+
+Internally Reek will convert this to the Regexp /write/.
+
+**A more sophisticated one:**
+
+```yaml
+FeatureEnvy:
+  exclude:
+    - "MyModel#do_things"
+    - "MyHelper"
+    - "ApplicationController#respond"
+```
+
+This would not report FeatureEnvy for the instance method `MyModel#do_things`, the whole module `MyHelper` and the `respond` instance method of `ApplicationController`
+
+## Advanced configuration
+
+Sometimes just strings are not enough for configuration. E.g. consider this code sample:
+
+```ruby
+class Klass
+  def foo1; end
+  def foo1bar; end
+end
+```
+Both "Klass#foo1" and "Klass#foo1bar" will smell of UncommunicativeMethodName. Now let's assume
+you are ok with "Klass#foo1" but not "Klass#foo1bar".
+Just having this configuration 
+
+```yaml
+UncommunicativeMethodName:
+  exclude:
+    - "Klass#foo1"
+```
+
+wouldn't work because now "Klass#foo1bar" wouldn't smell as well.
+
+For this reason Reek has a special syntax that allows you to use regexes by using a forward slash at the beginning and the end of the string.
+Everything within the forward slashes will be loaded as a regex.
+
+A possible configuration that hat excludes "Klass#foo1" from this scan but not "Klass#foo1bar" could look like this:
+
+```yaml
+UncommunicativeMethodName:
+  exclude:
+    - "/Klass#foo1$/"
+```
+
+## Reek 4
+
+In Reek 4 you could also pass regexes to `exclude`, meaning this was perfectly valid as well:
+
+```yaml
+DuplicateMethodCall:
+  exclude:
+    - !ruby/regexp /write/
+```
+
+Support for this has been scrapped with Reek 5 to make the Reek configuration more yaml standard compliant.
+You can still pass in regexes, you just have to wrap them into a string. Please see "Advanced configuration" above.

data/data/reek_docs/Boolean-Parameter.md

@@ -0,0 +1,54 @@
+# Boolean Parameter
+
+## Introduction
+
+_Boolean Parameter_ is a case of [Control Couple](Control-Couple.md), where a
+method parameter is defaulted to true or false. A _Boolean Parameter_
+effectively permits a method's caller to decide which execution path to take.
+This is a case of bad cohesion. You're creating a dependency between methods
+that is not really necessary, thus increasing coupling.
+
+## Example
+
+Given
+
+```ruby
+class Dummy
+  def hit_the_switch(switch = true)
+    if switch
+      puts 'Hitting the switch'
+      # do other things...
+    else
+      puts 'Not hitting the switch'
+      # do other things...
+    end
+  end
+end
+```
+
+Reek would emit the following warning:
+
+```
+test.rb -- 3 warnings:
+  [1]:Dummy#hit_the_switch has boolean parameter 'switch' (BooleanParameter)
+  [2]:Dummy#hit_the_switch is controlled by argument switch (ControlParameter)
+```
+
+Note that both smells are reported, _Boolean Parameter_ and _Control Parameter_.
+
+## Getting rid of the smell
+
+This is highly dependent on your exact architecture, but looking at the example above what you could do is:
+
+* Move everything in the `if` branch into a separate method
+* Move everything in the `else` branch into a separate method
+* Get rid of the `hit_the_switch` method altogether
+* Make the decision what method to call in the initial caller of `hit_the_switch`
+
+## Current support in Reek
+
+Reek can only detect a _Boolean Parameter_ when it has a default initializer like in the example above.
+
+## Configuration
+
+_Boolean Parameter_ supports the [Basic Smell Options](Basic-Smell-Options.md).

data/data/reek_docs/Class-Variable.md

@@ -0,0 +1,40 @@
+# Class Variable
+
+## Introduction
+
+Class variables form part of the global runtime state, and as such make it easy for one part of the system to accidentally or inadvertently depend on another part of the system. So the system becomes more prone to problems where changing something over here breaks something over there. In particular, class variables can make it hard to set up tests (because the context of the test includes all global state).
+
+For a detailed explanation, check out [this article](https://web.archive.org/web/20160714084532/http://4thmouse.com:80/index.php/2011/03/20/why-class-variables-in-ruby-are-a-bad-idea). and [Stackoverflow](https://stackoverflow.com/a/10594849/7798638)
+
+## Example
+
+Given
+
+```ruby
+class Dummy
+  @@class_variable = :whatever
+end
+```
+
+Reek would emit the following warning:
+
+```
+reek test.rb
+
+test.rb -- 1 warning:
+  [2]:Dummy declares the class variable @@class_variable (ClassVariable)
+```
+
+## Getting rid of the smell
+
+You can use class-instance variable to mitigate the problem (as also suggested in the linked article above):
+
+```ruby
+class Dummy
+  @class_variable = :whatever
+end
+```
+
+##  Configuration
+
+_Class Variable_ supports the [Basic Smell Options](Basic-Smell-Options.md).

data/data/reek_docs/Code-Smells.md

@@ -0,0 +1,39 @@
+# Code Smells
+
+Smells are indicators of where your code might be hard to read, maintain or evolve, rather than things that are specifically _wrong_. Naturally this means that Reek is looking towards your code's future (and that can make its reports seem somewhat subjective, of course).
+
+Reek currently includes checks for the following smells:
+
+* [Attribute](Attribute.md)
+* [Class Variable](Class-Variable.md)
+* [Control Couple](Control-Couple.md), including
+  * [Boolean Parameter](Boolean-Parameter.md)
+  * [Control Parameter](Control-Parameter.md)
+* [Data Clump](Data-Clump.md)
+* [Duplicate Method Call](Duplicate-Method-Call.md)
+* [Instance Variable Assumption](Instance-Variable-Assumption.md)
+* [Irresponsible Module](Irresponsible-Module.md)
+* [Large Class](Large-Class.md), including
+  * [Too Many Constants](Too-Many-Constants.md)
+  * [Too Many Instance Variables](Too-Many-Instance-Variables.md)
+  * [Too Many Methods](Too-Many-Methods.md)
+* [Long Parameter List](Long-Parameter-List.md), and its special case [Long Yield List](Long-Yield-List.md)
+* Low Cohesion, including
+  * [Feature Envy](Feature-Envy.md)
+  * [Utility Function](Utility-Function.md)
+* [Module Initialize](Module-Initialize.md)
+* [Nested Iterators](Nested-Iterators.md)
+* [Missing Safe Method](Missing-Safe-Method.md), formerly known as Prima Donna Method
+* [Simulated Polymorphism](Simulated-Polymorphism.md), including
+  * [Manual Dispatch](Manual-Dispatch.md)
+  * [Nil Check](Nil-Check.md)
+  * [Repeated Conditional](Repeated-Conditional.md)
+* [Subclassed From Core Class](Subclassed-From-Core-Class.md)
+* [Too Many Statements](Too-Many-Statements.md)
+* [Uncommunicative Name](Uncommunicative-Name.md), including
+  * [Uncommunicative Method Name](Uncommunicative-Method-Name.md)
+  * [Uncommunicative Module Name](Uncommunicative-Module-Name.md)
+  * [Uncommunicative Parameter Name](Uncommunicative-Parameter-Name.md)
+  * [Uncommunicative Variable Name](Uncommunicative-Variable-Name.md)
+* [Unused Parameters](Unused-Parameters.md)
+* [Unused Private Method](Unused-Private-Method.md)

data/data/reek_docs/Command-Line-Options.md

@@ -0,0 +1,119 @@
+# Command Line Options
+
+## Introduction
+
+Reek follows standard Unix convention for passing arguments.
+
+Check out
+
+```bash
+reek -h
+```
+
+for details.
+
+## Telling Reek to use a specific configuration file
+
+In case your configuration file is not in the standard location (that would be your project directory or
+whatever directory you're running Reek from) you can specify a configuration file with the `-c` option
+like this:
+
+```bash
+reek -c /somewhere/on/your/filesystem/reek_config.yml lib/
+```
+
+## Telling Reek Which Code to Check
+
+Probably the most standard use case would be to check all Ruby files in the lib directory:
+
+```bash
+reek lib/*.rb
+```
+
+In general, if any command-line argument is a directory, Reek searches that directory and all sub-directories for Ruby source files. Thus
+
+```bash
+reek lib
+```
+
+would be equivalent to
+
+```bash
+reek lib/**/*.rb
+```
+
+Occasionally you may want to quickly check a code snippet without going to the trouble of creating a file to hold it. You can pass the snippet directly to Reek's standard input:
+
+```bash
+echo "def x() true end" | reek
+```
+
+To just check all Ruby files in the current directory, you can simply run it
+with no parameters:
+
+```bash
+reek
+```
+
+## Telling Reek Which Smells to Detect
+
+You can tell Reek to only check particular smells by using the `--smell`
+option and passing in the smell name.
+
+For example, to only check for [Utility Function](Utility-Function.md), you
+would use:
+
+```bash
+reek --smell UtilityFunction
+```
+
+You can select several smells by repeating the `--smell` option like so:
+
+```bash
+reek --smell UtilityFunction --smell UncommunicativeMethodName
+```
+
+## Output options
+
+### Output smell's line number
+
+By passing in a "-n" flag to the _reek_ command, the output will suppress the line numbers:
+
+```bash
+$ reek -n mess.rb
+```
+
+```
+mess.rb -- 2 warnings:
+  x doesn't depend on instance state (UtilityFunction)
+  x has the name 'x' (UncommunicativeMethodName)
+```
+
+Otherwise line numbers will be shown as default at the beginning of each warning in square brackets:
+
+```bash
+$ reek mess.rb
+```
+
+```
+mess.rb -- 2 warnings:
+  [2]:x doesn't depend on instance state (UtilityFunction)
+  [2]:x has the name 'x' (UncommunicativeMethodName)
+```
+
+### Enable the verbose mode
+
+_reek_ has a verbose mode which you might find helpful as a beginner. "verbose" just means that behind each warning a helpful link will be displayed which leads directly to the corresponding _reek_ documentation page.
+This mode can be enabled via the "-U" or "--documentation" flag.
+
+So for instance, if your test file would smell of _ClassVariable_, this is what the _reek_ output would look like:
+
+```bash
+reek -U test.rb
+```
+```
+test.rb -- 1 warning:
+  [2]:Dummy declares the class variable @@class_variable (ClassVariable) [https://github.com/troessner/reek/blob/master/docs/Class-Variable.md]
+```
+
+Note the link at the end.

data/data/reek_docs/Control-Couple.md

@@ -0,0 +1,26 @@
+# Control Couple
+
+## Introduction
+
+Control coupling occurs when a method or block checks the value of a parameter
+in order to decide which execution path to take. The offending parameter is
+often called a _Control Couple_.
+
+Control Coupling is a kind of duplication, because the calling method already knows which path should be taken.
+
+Control Coupling reduces the code's flexibility by creating a dependency
+between the caller and callee: any change to the possible values of the
+controlling parameter must be reflected on both sides of the call. A _Control
+Couple_ also reveals a loss of simplicity: the called method probably has more
+than one responsibility, because it includes at least two different code paths.
+
+You can find a good write-up regarding this problem [here](https://solnic.codes/2012/04/11/get-rid-of-that-code-smell-control-couple/).
+
+## Current Support in Reek
+
+Reek performs the following checks that fall in this category:
+
+* [Control-Parameter](Control-Parameter.md) - a method parameter or block
+  parameter is the tested value in a conditional statement
+* [Boolean-Parameter](Boolean-Parameter.md) - a method parameter is defaulted
+  to `true` or `false`.