snoot 0.1.0

data/lib/snoot/cli.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "snoot/cli/event"
+require "snoot/cli/pipeline"
+
+module Snoot
+  # The CLI surface. cli.rb owns the surface entry points: argv-shape
+  # entry (.run -- UsageErrorExit), in-process entry (.run_invoked), the
+  # surface constants (banners, exit codes, the default path set), and
+  # the IO emitter helpers (emit_warnings, emit_failure,
+  # emit_nothing_to_report, format_report). The event values (RunInvoked,
+  # ReportEmitted) live in cli/event.rb; the Pipeline value lives in
+  # cli/pipeline.rb. .run consults BANNERS for --version, --help, and -h,
+  # rejects unknown flags with exit 64, and otherwise threads argv through
+  # .run_invoked, mapping the terminal outcome to an EXIT_CODES integer.
+  #
+  # The two entry points return deliberately different shapes. .run is
+  # the POSIX boundary: argv -> Integer, consumed by `exit
+  # Snoot::CLI.run(ARGV)` in exe/snoot. .run_invoked is the in-process
+  # boundary: Set<Path> -> [Run, Array of event values], used by tests
+  # and any library embedding that needs the full event list. Internally
+  # .run calls .run_invoked and projects Run#outcome through EXIT_CODES,
+  # so the integer is a lossy view of the Run; callers that need the Run,
+  # the events, or both must use .run_invoked.
+  module CLI
+    NOTHING_TO_REPORT = "nothing to report -- no findings above snoot's significance floor\n"
+    DEFAULT_PATHS = Set[Snoot::Path.new(raw: ".")].freeze
+
+    USAGE = <<~HELP
+      snoot - single-finding reek/flog/flay reporter
+
+      Usage: snoot [paths...]
+             snoot --version
+             snoot --help
+
+      With no path arguments, snoot scans the current directory.
+
+      Exit codes:
+        0   nothing to report
+        1   one finding rendered
+        2   analyser failure
+        64  usage error
+
+      Example:
+        snoot lib/
+    HELP
+
+    EXIT_CODES = {
+      finding_rendered: 1,
+      nothing_to_report: 0,
+      analysis_failed: 2,
+      usage_error: 64
+    }.freeze
+
+    BANNERS = {
+      %w[--version] => "snoot #{Snoot::VERSION}\n",
+      %w[-h --help] => USAGE
+    }.freeze
+
+    module_function
+
+    def emit_nothing_to_report(stdout)
+      stdout.write(NOTHING_TO_REPORT)
+      []
+    end
+
+    def emit_failure(run, stderr)
+      failure = run.failure
+      stderr.write("analysis failed (#{failure.analyser}): #{failure.message}\n")
+      []
+    end
+
+    def emit_warnings(analyse_events, stderr)
+      analyse_events.each do |event|
+        next unless event.is_a?(AnalyseRun::SkippedDocLessSmellWarned)
+
+        stderr.write("warning: skipping doc-less smell type '#{event.smell_type.name}'\n")
+      end
+    end
+
+    def format_report(sections)
+      "#{sections.values.join("\n\n")}\n"
+    end
+
+    def run(argv, pipeline: Pipeline.default)
+      banner = lookup_banner(argv)
+      return write_and_return(pipeline.stdout, banner, 0) if banner
+      return write_and_return(pipeline.stderr, USAGE, EXIT_CODES.fetch(:usage_error)) if unknown_flag?(argv)
+
+      run_pipeline(argv, pipeline: pipeline)
+    end
+
+    def lookup_banner(argv)
+      return nil unless argv.length == 1
+
+      BANNERS.find { |flags, _| flags.include?(argv.first) }&.last
+    end
+
+    def write_and_return(io, message, code)
+      io.write(message)
+      code
+    end
+
+    def unknown_flag?(argv)
+      argv.any? { |arg| arg.start_with?("-") }
+    end
+
+    def run_pipeline(argv, pipeline:)
+      run, _events = run_invoked(build_paths(argv), pipeline: pipeline)
+      EXIT_CODES.fetch(run.outcome)
+    end
+
+    def build_paths(argv)
+      argv.each_with_object(Set[]) { |raw, set| set << Path.new(raw: raw) }
+    end
+
+    def run_invoked(paths, pipeline: Pipeline.default)
+      paths = DEFAULT_PATHS if paths.empty?
+      collect_events(paths, pipeline)
+    end
+
+    def collect_events(paths, pipeline)
+      AnalyseRun.invoke(paths, orchestration: pipeline.orchestration) =>
+        { run:, events: analyse_events, smells: }
+      emit_warnings(analyse_events, pipeline.stderr)
+      events = [RunInvoked.new(paths: paths), *analyse_events,
+                *events_for_outcome(run, smells, pipeline: pipeline)]
+      [run, events]
+    end
+
+    def events_for_outcome(run, smells, pipeline:)
+      case run.outcome
+      when :finding_rendered then [emit_report(run, smells, pipeline: pipeline)]
+      when :nothing_to_report then emit_nothing_to_report(pipeline.stdout)
+      when :analysis_failed then emit_failure(run, pipeline.stderr)
+      else []
+      end
+    end
+
+    def emit_report(run, smells, pipeline:)
+      RenderReport.invoke(run, smells: smells, orchestration: pipeline.orchestration) =>
+        { sections:, finding: }
+      pipeline.stdout.write(format_report(sections))
+      ReportEmitted.new(run: run, finding: finding, sections: sections)
+    end
+  end
+end

data/lib/snoot/findings.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Snoot
+  # The three Finding variants -- the unit a Run can render. Distinct
+  # shapes; AnalyseRun's selection phase ranks within and across them.
+
+  # A single Reek smell instance. Ranked by how often its smell_type
+  # recurs within a Run.
+  Smell = Data.define(:smell_type, :location, :message)
+
+  # A single high-complexity method reported by Flog; score (BigDecimal)
+  # is the ranking key.
+  ComplexityHit = Data.define(:location, :method_name, :score)
+
+  # A structural-duplication cluster reported by Flay: a signature
+  # shared across two or more Locations. Cluster size (locations.size)
+  # is the ranking key.
+  DuplicationCluster = Data.define(:signature, :locations) do
+    def size = locations.size
+  end
+end

data/lib/snoot/render_report.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Snoot
+  # Given a finding_rendered Run, produces a Report. Smell findings get
+  # two sections (doc, instances); ComplexityHit and DuplicationCluster
+  # get three (header, finding_context, doc). Per-section content is
+  # built by the helpers below.
+  module RenderReport
+    # Report is the value returned by RenderReport.invoke: the source
+    # Run, the selected Finding it was built from, and the ordered
+    # sections hash that CLI joins into stdout output.
+    Report = Data.define(:run, :finding, :sections)
+
+    module_function
+
+    def invoke(run, smells:, orchestration:)
+      finding = run.selected_finding
+      sections = if finding.is_a?(Smell)
+                   smell_sections(smells, finding, orchestration)
+                 else
+                   non_smell_sections(finding)
+                 end
+      Report.new(run: run, finding: finding, sections: sections)
+    end
+
+    def smell_sections(smells, smell, orchestration)
+      smell_type = smell.smell_type
+      matching = smells.select { |instance| instance.smell_type == smell_type }
+      {
+        doc: orchestration.vendored_doc(smell_type),
+        instances: render_instances(matching)
+      }
+    end
+
+    def non_smell_sections(finding)
+      case finding
+      when ComplexityHit then complexity_hit_sections(finding)
+      when DuplicationCluster then duplication_cluster_sections(finding)
+      end
+    end
+
+    def complexity_hit_sections(hit)
+      loc = hit.location.description
+      score = hit.score.to_s("F")
+      name = hit.method_name
+      {
+        header: "High complexity in #{name} at #{loc} (score: #{score})",
+        finding_context: "#{loc}\n\nMethod: #{name}\nScore: #{score}",
+        doc: "High complexity hits indicate a method or class doing too much. " \
+             "Consider extracting helpers, simplifying conditionals, or " \
+             "splitting the responsibility across smaller units."
+      }
+    end
+
+    def duplication_cluster_sections(cluster)
+      locations = cluster.locations
+      rendered_locations = locations.map(&:description)
+      {
+        header: "Structural duplication: #{locations.size} locations (signature: #{cluster.signature})",
+        finding_context: "Locations:\n#{rendered_locations.join("\n")}",
+        doc: "Structural duplication suggests an extracted abstraction is missing. " \
+             "Consider whether the duplicated shape belongs to a single helper, " \
+             "module, or value type."
+      }
+    end
+
+    def render_instances(smells)
+      groups = smell_groups_by_path(smells)
+      "## Instances\n\n#{groups.map { |path, group| render_instance_group(path, group) }.join("\n\n")}"
+    end
+
+    def smell_groups_by_path(smells)
+      smells.group_by { |smell| smell.location.path.raw }
+            .sort_by { |path, group| [-group.size, path] }
+    end
+
+    def render_instance_group(path, smells)
+      lines = smells.map { |smell| "  Line #{smell.location.line_start}: #{smell.message}" }
+      "#{path}\n#{lines.join("\n")}"
+    end
+  end
+end

data/lib/snoot/run.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Snoot
+  # One analysis pass: the input paths, the outcome (pending,
+  # finding_rendered, nothing_to_report, analysis_failed), and the
+  # selected_finding when one was chosen. Enforces the transition rules
+  # and the presence invariants -- selected_finding iff finding_rendered,
+  # failure iff analysis_failed.
+  Run = Data.define(:paths, :outcome, :selected_finding, :failure) do
+    def initialize(paths:, outcome:, selected_finding: nil, failure: nil)
+      super
+      enforce_field_when!(:selected_finding, outcome: :finding_rendered)
+      enforce_field_when!(:failure, outcome: :analysis_failed)
+    end
+
+    def transition_to(target, selected_finding: nil, failure: nil)
+      raise StateError, "transition #{outcome} -> #{target} is not declared" unless outcome == :pending
+
+      with(outcome: target, selected_finding: selected_finding, failure: failure)
+    end
+
+    private
+
+    def enforce_field_when!(field_name, outcome:)
+      actual = self.outcome
+      field_value = public_send(field_name)
+      if actual == outcome
+        raise StateError, "#{field_name} required for :#{outcome}" unless field_value
+      elsif field_value
+        raise StateError,
+              "#{field_name} only permitted when outcome = :#{outcome} (got #{actual.inspect})"
+      end
+    end
+  end
+end

data/lib/snoot/state_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Snoot
+  # StateError signals a violation of the Run state machine: an
+  # undeclared outcome transition, or a missing/extraneous
+  # selected_finding or failure relative to the run's outcome.
+  class StateError < StandardError
+  end
+end

data/lib/snoot/value_types.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Snoot
+  # Value-type wrappers: no lifecycle, equal by value.
+
+  # A raw filesystem path string. Distinct from String so path-typed
+  # slots stay traceable.
+  Path = Data.define(:raw)
+
+  # A source range: inclusive line_start/line_end at a Path. Used by
+  # Smell, ComplexityHit, and each DuplicationCluster entry; carries its
+  # own #description so the AnalyserOrchestration contract need not.
+  Location = Data.define(:path, :line_start, :line_end) do
+    def description = "#{path.raw}:#{line_start}-#{line_end}"
+  end
+
+  # A Reek smell category, named (e.g. "IrresponsibleModule"). Groups
+  # Smells for ranking; keys vendored-doc lookup.
+  SmellType = Data.define(:name)
+end

data/lib/snoot/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Snoot
+  VERSION = "0.1.0"
+end

data/lib/snoot.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Top-level namespace for the snoot gem. See `snoot.allium` for the
+# behavioural specification this implementation realises.
+module Snoot
+end
+
+require "snoot/version"
+require "snoot/state_error"
+require "snoot/value_types"
+require "snoot/findings"
+require "snoot/analyser_result"
+require "snoot/run"
+require "snoot/analyse_run"
+require "snoot/analyse_run/result"
+require "snoot/analyse_run/decision"
+require "snoot/render_report"
+require "snoot/analyser_orchestration"
+require "snoot/analyser_orchestration/result_mapping"
+require "snoot/analyser_orchestration/default"
+require "snoot/cli"