snoot 0.1.0

data/data/reek_docs/Unused-Private-Method.md

@@ -0,0 +1,101 @@
+## Introduction
+
+Classes should use their private methods. Otherwise this is dead
+code which is confusing and bad for maintenance.
+
+The _Unused Private Method_ detector reports unused private instance
+methods and instance methods only - class methods are ignored.
+
+## Example
+
+Given:
+
+```ruby
+class Car
+  private
+  def drive; end
+  def start; end
+end
+```
+
+Reek would emit the following warning:
+
+```
+2 warnings:
+  [3]:Car has the unused private instance method `drive` (UnusedPrivateMethod)
+  [4]:Car has the unused private instance method `start` (UnusedPrivateMethod)
+```
+
+## Configuration
+
+_Unused Private Method_ offers the [Basic Smell Options](Basic-Smell-Options.md).
+
+Private methods that are called via dynamic dispatch
+will trigger a false alarm since detecting something like this is far out of
+scope for Reek. In this case you can disable this detector via the `exclude`
+configuration option (which is part of the [Basic Smell Options](Basic-Smell-Options.md))
+for instance like this (an example from Reek's own codebase):
+
+```ruby
+# :reek:UnusedPrivateMethod { exclude: [ process_ ] }
+class ContextBuilder
+  def process_begin
+    # ....
+  end
+end
+```
+
+Note that disabling this detector via comment works on a class scope, not
+a method scope (like you can see above).
+
+Another simple example would be:
+
+```ruby
+class Alfa
+  private
+  def bravo
+  end
+end
+```
+
+This would report:
+
+>>
+ruby.rb -- 1 warning:
+  [3]:UnusedPrivateMethod: Alfa has the unused private instance method 'bravo'
+
+If you want to suppress this warning you can do this via source comment like this:
+
+```ruby
+# :reek:UnusedPrivateMethod: { exclude: bravo }
+class Alfa
+  private
+  def bravo
+  end
+end
+```
+
+## Known limitations
+
+* Method calls via dynamic dispatch (e.g. via `send`) is something Reek (or any other
+  static tool for that matter) cannot detect.
+* Method calls via callback like [Rails filters](http://guides.rubyonrails.org/action_controller_overview.html#filters)
+  will trigger this as well, e.g.:
+
+```ruby
+  class BankController < ActionController::Base
+    before_action :audit
+
+    private
+    def audit
+      # ....
+    end
+  end
+```
+* Reek works on a per-file base. This means that using something like the [template pattern](https://en.wikipedia.org/wiki/Template_method_pattern)
+  with private methods will trigger this detector.
+  We do believe though that using private methods to fill out a template in a
+  superclass is not a good idea in general so this probably isn't really a problem
+  but still worth mentioning it.
+
+

data/data/reek_docs/Utility-Function.md

@@ -0,0 +1,57 @@
+# Utility Function
+
+## Introduction
+
+A _Utility Function_ is any instance method that has no dependency on the state of the instance.
+
+_Utility Function_ is heavily related to _[Feature Envy](Feature-Envy.md)_, please check out the explanation there why _Utility Function_ is something you should care about.
+
+## Example
+
+Given
+
+```ruby
+class UtilityFunction
+  def showcase(argument)
+    argument.to_s + argument.to_i
+  end
+end
+```
+
+Reek would report:
+
+```
+test.rb -- 2 warnings:
+  [2]:UtilityFunction#showcase doesn't depend on instance state (UtilityFunction)
+```
+
+## Current Support in Reek
+
+_Utility Function_ will warn about any method that:
+
+* is non-empty
+* does not override an inherited method
+* calls at least one method on another object
+* doesn't use any of self's instance variables
+* doesn't use any of self's methods
+
+## Differences to _Feature Envy_
+
+_[Feature Envy](Feature-Envy.md)_ is only triggered if there are some references to self and _Utility Function_ is triggered if there are no references to self.
+
+## Configuration
+
+Reek's _Utility Function_ detector supports the [Basic Smell Options](Basic-Smell-Options.md), plus:
+
+| Option                | Value       | Effect  |
+| ----------------------|-------------|---------|
+| `public_methods_only` | Boolean | Disable this smell detector for non-public methods (which means "private" and "protected") |
+
+A sample configuration file would look like this:
+
+```yaml
+---
+detectors:
+  UtilityFunction:
+    public_methods_only: true
+```

data/data/reek_docs/Versioning-Policy.md

@@ -0,0 +1,7 @@
+# Versioning Policy
+
+* CLI interface: Adding options is a non-breaking change, and would warrant an update of the minor version. Removing options is a breaking change and requires a major version update (we did this going to Reek 2). Adding a report format probably also warrants a minor version upgrade.
+* API: We haven't really defined a 'public' API for using Reek programmatically, and we've only just started testing it. So, this is basically a blank slate at the moment. We will work on this as a part of the Reek 3 release.
+* List of detected smells: Adding a smell warrants a minor release, removing a smell is a breaking change. This makes sense if you consider that the CLI allows running a single smell detector.
+* Consistency of detected smells: This is very hard to guarantee. If we fix a bug in one of the detectors, some fragrant code may become smelly, or vice versa. Right now we don't bother with this.
+* Smell configuration: The detectors are quite tolerant regarding configuration options that they don't recognize, so we regard any change here as only requiring a minor release.

data/data/reek_docs/YAML-Reports.md

@@ -0,0 +1,93 @@
+# YAML Reports
+
+## Introduction
+
+Reek's `--yaml` option writes on $stdout a YAML dump of the smells found. Each reported smell has a number of standard fields and a number of fields that are specific to the smell's type. The common fields are as follows:
+
+| Field         | Type       | Value  |
+| ---------------|-------------|---------|
+| source | string | The name of the source file containing the smell, or `$stdin` |
+| lines | array | The source file line number(s) that contribute to this smell |
+| context | string | The name of the class, module or method containing the smell |
+| class | string | The class to which this smell belongs |
+| subclass | string | This smell's subclass within the above class |
+| message | string | The message that would have been printed in a standard Reek report |
+| is_active | boolean | `false` if the smell is masked by a config file; `true` otherwise |
+
+All of these fields are grouped into hashes `location`, `smell` and `status` (see the examples below).
+
+## Examples
+
+Duplication:
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    - 7
+    context: Dirty#a
+  smell: 
+    class: Duplication
+    subclass: DuplicateMethodCall
+    occurrences: 2
+    call: puts(@s.title)
+    message: calls puts(@s.title) twice
+  status:
+    is_active: true
+</pre>
+
+[Nested Iterators](Nested-Iterators.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: NestedIterators
+    subclass: ""
+    depth: 2
+    message: contains iterators nested 2 deep
+  status:
+    is_active: true
+</pre>
+
+[Uncommunicative Method Name](Uncommunicative-Method-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 3
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeMethodName
+    method_name: a
+    message: has the name 'a'
+  status:
+    is_active: false
+</pre>
+
+[Uncommunicative Variable Name](Uncommunicative-Variable-Name.md):
+
+<pre>
+- !ruby/object:Reek::SmellWarning 
+  location: 
+    source: spec/samples/masked/dirty.rb
+    lines: 
+    - 5
+    context: Dirty#a
+  smell: 
+    class: UncommunicativeName
+    subclass: UncommunicativeVariableName
+    variable_name: x
+    message: has the variable name 'x'
+  status:
+    is_active: true
+</pre>

data/exe/snoot

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "snoot"
+exit Snoot::CLI.run(ARGV)

data/lib/snoot/analyse_run/decision.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Snoot
+  module AnalyseRun
+    # Internal collaborator: bundles an AnalyserOrchestration with the
+    # Sources it produced so the chained selection helpers can share
+    # both as state instead of threading the pair through every call.
+    class Decision
+      def initialize(orchestration:, sources:)
+        @orchestration = orchestration
+        @sources = sources
+      end
+
+      def resolve(run)
+        selected = selected_candidate
+        terminal = if selected
+                     run.transition_to(:finding_rendered, selected_finding: selected)
+                   else
+                     run.transition_to(:nothing_to_report)
+                   end
+        Result.new(run: terminal, events: doc_less_events(terminal), smells: @sources.smells)
+      end
+
+      private
+
+      def selected_candidate
+        AnalyseRun.select_top_finding(candidates)
+      end
+
+      def candidates
+        documented = @orchestration.significant_smells(@sources.smells)
+                                   .select { |smell| @orchestration.vendored_doc(smell.smell_type) }
+                                   .to_set
+        documented |
+          @orchestration.significant_complexities(@sources.complexities) |
+          @orchestration.significant_duplications(@sources.duplications)
+      end
+
+      def top_significant_smell
+        significant = @orchestration.significant_smells(@sources.smells)
+        AnalyseRun.top_smell(significant) if significant.any?
+      end
+
+      def doc_less_smell_type
+        smell = top_significant_smell
+        return nil unless smell
+
+        smell_type = smell.smell_type
+        return nil if @orchestration.vendored_doc(smell_type)
+
+        smell_type
+      end
+
+      def doc_less_events(run)
+        smell_type = doc_less_smell_type
+        return [] unless smell_type
+
+        [SkippedDocLessSmellWarned.new(run: run, smell_type: smell_type)]
+      end
+    end
+  end
+end

data/lib/snoot/analyse_run/result.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Snoot
+  module AnalyseRun
+    # Result is the value returned by AnalyseRun.invoke: the terminal Run,
+    # the audit events emitted along the way, and the smells the
+    # orchestration produced (forwarded to RenderReport, which filters
+    # by selected smell_type when building the per-file Instances list).
+    # smells is empty when analysis failed (no Sources were produced).
+    Result = Data.define(:run, :events, :smells)
+  end
+end

data/lib/snoot/analyse_run.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Snoot
+  # Turns a pending Run into a terminal outcome: orchestrates the three
+  # analysers, then selects one finding (or none, or signals failure).
+  # `invoke` returns an AnalyseRun::Result carrying the terminal Run, the
+  # events emitted along the way, and the raw smell set the orchestration
+  # produced.
+  module AnalyseRun
+    # SkippedDocLessSmellWarned carries the terminal Run and the
+    # offending smell_type that lacked a vendored doc.
+    SkippedDocLessSmellWarned = Data.define(:run, :smell_type)
+
+    module_function
+
+    def invoke(paths, orchestration:)
+      run = Run.new(paths: paths, outcome: :pending)
+      result = orchestration.analyse(paths)
+      return analysis_failure(run, result) if result.is_a?(AnalyserFailure)
+
+      Decision.new(orchestration: orchestration, sources: result).resolve(run)
+    end
+
+    def analysis_failure(run, failure)
+      failed = run.transition_to(:analysis_failed, failure: failure)
+      Result.new(run: failed, events: [], smells: Set[])
+    end
+
+    def select_top_finding(findings)
+      top_smell(findings.grep(Smell)) ||
+        top_duplication(findings.grep(DuplicationCluster)) ||
+        top_complexity(findings.grep(ComplexityHit))
+    end
+
+    def top_smell(smells)
+      counts = smells.group_by(&:smell_type).transform_values(&:size)
+      top_by(smells, metric: ->(smell) { counts[smell.smell_type] }, &method(:smell_sort_key))
+    end
+
+    def top_duplication(clusters)
+      top_by(clusters, metric: :size, &method(:duplication_sort_key))
+    end
+
+    def top_complexity(complexities)
+      top_by(complexities, metric: :score, &method(:complexity_sort_key))
+    end
+
+    def top_by(items, metric:, &sort_key)
+      pick = metric.to_proc
+      max = items.map(&pick).max
+      items.select { |item| pick.call(item) == max }.min_by(&sort_key)
+    end
+
+    def smell_sort_key(smell)
+      type = smell.smell_type
+      loc = smell.location
+      [type.name, loc.path.raw, loc.line_start]
+    end
+
+    def duplication_sort_key(cluster)
+      locs = cluster.locations
+      [cluster.signature, locs.map { |loc| loc.path.raw }.min, locs.map(&:line_start).min]
+    end
+
+    def complexity_sort_key(hit)
+      loc = hit.location
+      [loc.path.raw, loc.line_start]
+    end
+  end
+end

data/lib/snoot/analyser_orchestration/default.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "flay"
+require "flog"
+require "path_expander"
+require "reek"
+require "reek/cli/options"
+require "reek/configuration/app_configuration"
+require "reek/source/source_locator"
+
+module Snoot
+  module AnalyserOrchestration
+    # Default is the production adapter for AnalyserOrchestration. It
+    # invokes the real Reek/Flog/Flay APIs in-process (no shellouts) and
+    # resolves vendored_doc against the reek docs vendored at
+    # data/reek_docs/<PascalCase-Hyphen>.md (synced via `rake docs:sync`,
+    # pinned to the bundled reek version). Reek invocation honours a
+    # project-local `.reek.yml` (or any ancestor's, falling back to
+    # `~/.reek.yml`) via `AppConfiguration.from_default_path`, matching
+    # reek's own CLI discovery. Flog scoring uses Flog's default options
+    # (every scored method emits a ComplexityHit; selection happens in
+    # AnalyseRun). Flay duplication uses Flay's default mass threshold
+    # (16). Stateless: implemented as a module of module functions, used
+    # as the orchestration value directly (no `.new`).
+    #
+    # Default's public surface is exactly the five contracted methods
+    # (vendored_doc, significant_smells, significant_complexities,
+    # significant_duplications, analyse). The per-analyser drivers
+    # (reek_analyse, flog_analyse, flay_analyse) and the per-pathname
+    # helper (reek_smells_for) are private; their behaviour is observed
+    # through analyse. Pure third-party-output translation is delegated
+    # to the sibling module ResultMapping.
+    #
+    # Per-analyser directory expansion mirrors each tool's own CLI
+    # default rather than imposing a snoot-wide glob, so a directory
+    # Path resolves exactly as that tool would resolve it on the command
+    # line. Reek defers to `Reek::Source::SourceLocator` (which also
+    # honours `.reek.yml exclude_paths`); Flog uses `**/*.{rb,rake}` to
+    # match `Flog::CLI`; Flay uses `**/*.rb` (Flay's CLI additionally
+    # appends extensions advertised by installed Flay plugins, which
+    # snoot does not load). The orchestration contract is path-abstract
+    # (snoot.allium:150), so this is implementation policy each adapter
+    # owns.
+    module Default
+      DOCS_ROOT = File.expand_path("../../../data/reek_docs", __dir__).freeze
+      DOC_FILENAME_PATTERN = /([a-z])([A-Z])/
+
+      SMELL_TYPE_INSTANCE_FLOOR = 2
+      COMPLEXITY_SCORE_FLOOR = BigDecimal("25")
+
+      ANALYSER_PROBES = [
+        %i[reek reek_analyse],
+        %i[flog flog_analyse],
+        %i[flay flay_analyse]
+      ].freeze
+
+      # Memoises vendored_doc results by smell_type.name. The corpus is
+      # fixed at gem build time (DOCS_ROOT, pinned to bundled reek) and
+      # the @invariant Determinism contract treats each call pure within
+      # a single CLI invocation, so caching across calls within a
+      # process is safe. nil (missing-doc) results are cached too.
+      @vendored_doc_cache = {}
+
+      module_function
+
+      def reek_analyse(paths)
+        config = Reek::Configuration::AppConfiguration.from_default_path
+        Reek::Source::SourceLocator.new(paths.map(&:raw), configuration: config).sources
+                                   .flat_map { |pathname| reek_smells_for(pathname, config) }
+                                   .to_set
+      end
+
+      def reek_smells_for(pathname, config)
+        examiner = Reek::Examiner.new(pathname, configuration: config)
+        examiner.smells.filter_map do |warning|
+          next unless warning.lines&.any?
+
+          ResultMapping.smell_from_reek_warning(warning)
+        end
+      end
+
+      def flog_analyse(paths)
+        files = PathExpander.new(paths.map(&:raw), "**/*.{rb,rake}").process
+        flog = Flog.new
+        flog.flog(*files)
+        flog.totals.filter_map do |class_method, score|
+          ResultMapping.complexity_hit_from_flog_entry(
+            class_method: class_method, score: score,
+            raw_location: flog.method_locations[class_method]
+          )
+        end.to_set
+      end
+
+      def flay_analyse(paths)
+        files = PathExpander.new(paths.map(&:raw), "**/*.rb").process
+        flay = Flay.new
+        flay.process(*files)
+        flay.analyze.each_with_object(Set[]) do |item, clusters|
+          clusters << ResultMapping.duplication_cluster_from_flay_item(item)
+        end
+      end
+
+      def vendored_doc(smell_type)
+        name = smell_type.name
+        @vendored_doc_cache.fetch(name) do
+          path = File.join(DOCS_ROOT, "#{name.gsub(DOC_FILENAME_PATTERN, '\1-\2')}.md")
+          @vendored_doc_cache[name] = File.exist?(path) ? File.read(path) : nil
+        end
+      end
+
+      def significant_smells(smells)
+        counts = smells.group_by(&:smell_type).transform_values(&:size)
+        smells.select { |smell| counts[smell.smell_type] >= SMELL_TYPE_INSTANCE_FLOOR }.to_set
+      end
+
+      def significant_complexities(complexities)
+        complexities.select { |hit| hit.score >= COMPLEXITY_SCORE_FLOOR }.to_set
+      end
+
+      def significant_duplications(duplications) = duplications
+
+      # analyse runs the three analysers in canonical order (Reek ->
+      # Flog -> Flay), capturing each result as it succeeds. On the
+      # first failure it returns an AnalyserFailure tagged with that
+      # analyser and does not invoke the remaining ones. On full
+      # success it returns a Sources bundling the three result sets.
+      def analyse(paths)
+        outputs = collect_outputs(paths)
+        return outputs if outputs.is_a?(AnalyserFailure)
+
+        Sources.new(
+          smells: outputs[:reek], complexities: outputs[:flog], duplications: outputs[:flay]
+        )
+      end
+
+      def collect_outputs(paths)
+        ANALYSER_PROBES.each_with_object({}) do |(tag, method), outputs|
+          outputs[tag] = send(method, paths)
+        rescue StandardError => error
+          return AnalyserFailure.new(analyser: tag, message: error.message)
+        end
+      end
+
+      private_class_method :reek_analyse, :reek_smells_for, :flog_analyse, :flay_analyse,
+                           :collect_outputs
+    end
+  end
+end

data/lib/snoot/analyser_orchestration/result_mapping.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Snoot
+  module AnalyserOrchestration
+    # ResultMapping converts third-party analyser outputs (Reek warnings,
+    # Flog totals entries, Flay items) into Snoot value objects. Pure: no
+    # IO, no third-party invocation. Default consumes these mappers
+    # internally as it drives reek/flog/flay; tests target this module's
+    # public surface directly with input doubles.
+    module ResultMapping
+      module_function
+
+      def smell_from_reek_warning(warning)
+        lines = warning.lines
+        Smell.new(
+          smell_type: SmellType.new(name: warning.smell_type),
+          location: Location.new(
+            path: Path.new(raw: warning.source),
+            line_start: lines.first,
+            line_end: lines.last
+          ),
+          message: "#{warning.context} #{warning.message}"
+        )
+      end
+
+      # Flog stores method locations as "file:line" or "file:line-line_max".
+      # Returns nil when the entry is missing (e.g. main#none) so callers
+      # can skip top-level expressions that lack a method-level location.
+      def complexity_hit_from_flog_entry(class_method:, score:, raw_location:)
+        file, range = raw_location.to_s.split(":", 2)
+        return unless file && range
+
+        line_start, = range.split("-", 2).map(&:to_i)
+        ComplexityHit.new(
+          location: Location.new(path: Path.new(raw: file), line_start: line_start, line_end: line_start),
+          method_name: class_method,
+          score: BigDecimal(score.to_s)
+        )
+      end
+
+      def duplication_cluster_from_flay_item(item)
+        locations = item.locations.each_with_object(Set[]) do |loc, set|
+          line = loc.line
+          set << Location.new(path: Path.new(raw: loc.file), line_start: line, line_end: line)
+        end
+        DuplicationCluster.new(signature: item.structural_hash.to_s, locations: locations)
+      end
+    end
+  end
+end

data/lib/snoot/analyser_orchestration.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Snoot
+  # The duck-typed orchestration contract the CLI demands -- any object
+  # responding to these five methods qualifies (no base class to inherit):
+  #
+  #   vendored_doc(smell_type) -> String?
+  #   significant_smells(smells) -> Set<Smell>
+  #   significant_complexities(complexities) -> Set<ComplexityHit>
+  #   significant_duplications(duplications) -> Set<DuplicationCluster>
+  #   analyse(paths) -> Sources | AnalyserFailure
+  #
+  # Each call is pure within a single CLI invocation (see snoot.allium's
+  # Determinism invariant); outputs may differ across invocations as the
+  # source under analysis changes -- not a violation. The test double is
+  # Snoot::Spec::FakeOrchestration; the production adapter is
+  # Snoot::AnalyserOrchestration::Default. Report location rendering is
+  # Snoot::Location#description's job, not this contract's.
+  module AnalyserOrchestration
+  end
+end

data/lib/snoot/analyser_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Snoot
+  # The two results of AnalyserOrchestration#analyse: Sources on full
+  # success, AnalyserFailure on the first analyser error.
+
+  # `analyser` is one of :reek, :flog, :flay (canonical order) -- which
+  # analyser failed; `message` is the error detail surfaced on stderr.
+  AnalyserFailure = Data.define(:analyser, :message)
+
+  # The three analyser outputs bundled for one Run; consumed by
+  # AnalyseRun's selection phase.
+  Sources = Data.define(:smells, :complexities, :duplications)
+end

data/lib/snoot/cli/event.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Snoot
+  module CLI
+    # RunInvoked carries the (possibly defaulted) path set at the
+    # moment the surface is entered.
+    RunInvoked = Data.define(:paths)
+
+    # ReportEmitted carries the terminal Run, the selected Finding, and
+    # the rendered sections produced by RenderReport.
+    ReportEmitted = Data.define(:run, :finding, :sections)
+  end
+end

data/lib/snoot/cli/pipeline.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Snoot
+  module CLI
+    # Pipeline bundles the analyser orchestration and the stdout/stderr
+    # pair that together define a CLI invocation's wiring -- the trio
+    # flows through run_invoked, the outcome dispatch, and emit_report.
+    Pipeline = Data.define(:orchestration, :stdout, :stderr) do
+      def self.default
+        new(orchestration: AnalyserOrchestration::Default, stdout: $stdout, stderr: $stderr)
+      end
+    end
+  end
+end