hashira 0.6.0 → 0.8.0

data/lib/hashira/ci/finding_diff_report.rb

@@ -8,6 +8,7 @@ class Hashira::CI::FindingDiffReport
 
   def print(diff)
     introduced(diff.added).each { emit(it) }
+    aggravated(diff.worsened).each { |finding, before, after| regressed(finding, before, after) }
     Hashira::CI::Improvement.new("Findings resolved", io: @io).print(diff.removed)
   end
 
@@ -15,6 +16,15 @@ class Hashira::CI::FindingDiffReport
 
   def introduced(added) = added.filter_map { |signature| @findings.find { it.signature == signature } }
 
+  def aggravated(worsened)
+    worsened.map { |signature, before, after| [@findings.find { it.signature == signature }, before, after] }
+  end
+
+  def regressed(finding, before, after)
+    @io.puts("WORSE FINDING (was #{before}, now #{after}):")
+    Hashira::Report::FindingLines.new(finding, indent: "  ", io: @io).emit
+  end
+
   def emit(finding)
     @io.puts("NEW FINDING:")
     Hashira::Report::FindingLines.new(finding, indent: "  ", io: @io).emit

data/lib/hashira/ci/gate.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
 class Hashira::CI::Gate
-  def initialize(findings, kinds, io: $stdout)
+  def initialize(findings, kinds, io: $stdout, error: $stderr)
     @findings = findings
     @kinds = kinds
     @io = io
+    @error = error
   end
 
   def check
@@ -16,10 +17,17 @@ class Hashira::CI::Gate
 
   def failure(offending)
     offending.each { Hashira::Report::FindingLines.new(it, io: @io).print }
-    @io.puts("\nGate FAILED: #{offending.size} finding(s) of kind #{@kinds.join(", ")}.")
+    verdict = "Gate FAILED: #{offending.size} finding(s) — #{tally(offending)}."
+    @io.puts("\n#{verdict}")
+    @error.puts(verdict)
     1
   end
 
+  def tally(offending)
+    offending.group_by(&:kind).map { |kind, list| [kind, list.size] }
+      .sort_by { |kind, size| [-size, kind] }.map { |kind, size| "#{kind} #{size}" }.join(", ")
+  end
+
   def clean
     @io.puts("Gate OK: no findings of kind #{@kinds.join(", ")}.")
     0

data/lib/hashira/ci/improvement.rb

@@ -9,6 +9,6 @@ class Hashira::CI::Improvement
   def print(removed)
     return if removed.empty?
     @io.puts("#{@label} (improvement!): #{removed.join(", ")}")
-    @io.puts("Lock it in: hashira --update-baseline")
+    @io.puts("Lock it in: re-run this command with --update-baseline")
   end
 end

data/lib/hashira/ci/ratchet.rb

@@ -1,30 +1,57 @@
 # frozen_string_literal: true
 
 class Hashira::CI::Ratchet
-  def initialize(graph, findings, baseline_path, io: $stdout)
+  def initialize(graph, findings, baseline, io: $stdout)
     @graph = graph
     @findings = findings
-    @baseline = Hashira::CI::Baseline.load(baseline_path)
+    @baseline = baseline
     @io = io
   end
 
   def update
-    @baseline.write(edges, digests, packaging:)
-    @io.puts("Baseline updated: #{edges.size} edges, #{digests.size} findings.")
-    0
+    @baseline.write(edges, scored, packaging:)
+    @io.puts("Baseline updated: #{edges.size} edges, #{recorded}.")
+    Hashira::CI::Status::CLEAN
   end
 
-  def check = Hashira::CI::RatchetReport.new(@graph, @findings, io: @io).print(drift, delta)
+  def check(focus)
+    compared = focus.narrowing? ? Hashira::CI::Slice.new(@baseline) : Hashira::CI::Sweep.new(@baseline)
+    Hashira::CI::RatchetReport.new(@graph, @findings, io: @io)
+      .print(compared.edges(drift), delta(compared), tally(compared))
+  end
 
   def blocker
     return "no baseline at #{@baseline.path} — run --update-baseline first" unless @baseline.exist?
-    mismatch unless @baseline.packaging == packaging
+    drifted.first
   end
 
   private
 
+  def drifted = [(mismatch unless @baseline.packaging == packaging), *narrowed(@baseline.wanted)].compact
+
+  def narrowed(wanted)
+    [
+      widened("the analyzers", @baseline.analyzers, wanted[:analyzers]),
+      widened("the directories", @baseline.targets, wanted[:targets])
+    ]
+  end
+
+  def widened(flag, was, now)
+    return if was == now
+    phrase(flag, was, now)
+  end
+
+  def phrase(flag, was, now)
+    "baseline #{@baseline.path} was recorded with #{flag} #{was.join(", ")}, but this run " \
+      "uses #{now.join(", ")} — rerun the recorded way, or refresh it with --update-baseline"
+  end
+
   def packaging = @graph.packaging.to_s
 
+  def recorded = collapsed(@findings.size, scored.size)
+
+  def collapsed(total, keys) = keys == total ? "#{total} findings" : "#{total} findings (#{keys} distinct)"
+
   def mismatch
     recorded = @baseline.packaging
     "baseline #{@baseline.path} was recorded with --package-by #{recorded}, but this run " \
@@ -33,13 +60,17 @@ class Hashira::CI::Ratchet
 
   def edges = @graph.edges.map(&:to_s)
 
-  def digests = @findings.map(&:signature).uniq.sort
+  def tally(compared) = compared.counts("#{@graph.edges.size} edges", "#{@findings.size} findings").join(", ")
+
+  def scored
+    @_scored ||= @findings.group_by(&:signature).sort.to_h { |key, group| [key, group.filter_map(&:magnitude).max] }
+  end
 
   def drift = Hashira::CI::Diff.new(added: fresh, removed: @baseline.edges - edges)
 
   def fresh = @graph.edges.reject { @baseline.edges.include?(it.to_s) }
 
-  def delta
-    Hashira::CI::Diff.between(digests, @baseline.findings) if @baseline.findings?
+  def delta(compared)
+    compared.findings(scored) if @baseline.findings?
   end
 end

data/lib/hashira/ci/ratchet_report.rb

@@ -7,22 +7,24 @@ class Hashira::CI::RatchetReport
     @io = io
   end
 
-  def print(edges, findings)
-    return unchanged if quiet?(edges, findings)
+  def print(edges, findings, tally)
+    return unchanged(tally) if quiet?(edges, findings)
     details(edges, findings)
     advice(edges, findings)
-    1
+    verdict(edges, findings)
   end
 
   private
 
   def quiet?(*diffs) = diffs.compact.all?(&:empty?)
 
-  def unchanged
-    @io.puts("Ratchet OK: #{@graph.edges.size} edges, #{@findings.size} findings, unchanged.")
-    0
+  def unchanged(tally)
+    @io.puts("Ratchet OK: #{tally}, unchanged.")
+    Hashira::CI::Status::CLEAN
   end
 
+  def verdict(*diffs) = diffs.compact.any?(&:worse?) ? Hashira::CI::Status::WORSE : Hashira::CI::Status::BETTER
+
   def details(edges, findings)
     Hashira::CI::EdgeDiffReport.new(@graph, io: @io).print(edges)
     Hashira::CI::FindingDiffReport.new(@findings, io: @io).print(findings) if findings

data/lib/hashira/ci/scope.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Hashira
+  module CI
+    Scope =
+      Data.define(:analyzers, :targets) do
+        def to_h = { analyzers: analyzers.map(&:to_s).sort, targets: targets.sort }
+      end
+  end
+end

data/lib/hashira/ci/slice.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Hashira::CI::Slice
+  SETTLED = Hashira::CI::Diff.new(added: [], removed: [])
+
+  def initialize(baseline)
+    @baseline = baseline
+  end
+
+  def edges(_diff) = SETTLED
+
+  def findings(scored) = Hashira::CI::Comparison.new(scored, seen(scored)).diff
+
+  def seen(scored) = @baseline.findings.slice(*scored.keys)
+
+  def counts(_edges, findings) = [findings]
+end

data/lib/hashira/ci/status.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Hashira::CI::Status
+  CLEAN = 0
+  WORSE = 1
+  BETTER = 3
+end

data/lib/hashira/ci/sweep.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+class Hashira::CI::Sweep
+  def initialize(baseline)
+    @baseline = baseline
+  end
+
+  def edges(diff) = diff
+
+  def findings(scored) = Hashira::CI::Comparison.new(scored, @baseline.findings).diff
+
+  def counts(edges, findings) = [edges, findings]
+end

data/lib/hashira/cli/arguments.rb

@@ -1,23 +1,32 @@
 # frozen_string_literal: true
 
 class Hashira::CLI::Arguments
-  def initialize(argv)
-    @argv = argv.dup
+  def initialize(given)
+    @given = given
   end
 
   def take(flag, default)
-    position = @argv.index(flag)
+    position = argv.index(flag)
     return default unless position
-    _flag, value = @argv.slice!(position, 2)
-    raise(Hashira::Error, "#{flag} needs a value") unless value
+    _flag, value = argv.slice!(position, 2)
+    vet(flag, value)
+  end
+
+  def vet(flag, value)
+    raise(Hashira::Error, "#{flag} needs a value") if value.to_s.strip.empty?
+    raise(Hashira::Error, "#{flag} given more than once") if argv.include?(flag)
     value
   end
 
-  def delete(flag) = @argv.delete(flag)
+  def delete(flag) = argv.delete(flag)
 
   def rest
-    stray = @argv.find { it.start_with?("-") }
+    stray = argv.find { it.start_with?("-") }
     raise(Hashira::Error, "unknown option #{stray}") if stray
-    @argv
+    argv
   end
+
+  private
+
+  def argv = @_argv ||= @given.dup
 end

data/lib/hashira/cli/choice.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Choice
+  module_function
+
+  def unknown(flag, value, choices)
+    Hashira::Error.new("unknown #{flag} #{value.inspect} (use: #{choices.join(", ")})")
+  end
+end

data/lib/hashira/cli/command_line.rb

@@ -2,23 +2,26 @@
 
 class Hashira::CLI::CommandLine
   def initialize(argv)
-    @arguments = Hashira::CLI::Arguments.new(argv)
+    @argv = argv
   end
 
   def options = page || parsed
 
   private
 
+  def arguments = @_arguments ||= Hashira::CLI::Arguments.new(@argv)
+
   def page
     flag = Hashira::CLI::FLAGS.select(&:page?).find { seen?(it) }
-    Hashira::CLI::Options.page(flag.mode) if flag
+    Hashira::CLI::Options.build(flag.mode) if flag
   end
 
-  def seen?(flag) = flag.names.any? { @arguments.delete(it) }
+  def seen?(flag) = flag.names.any? { arguments.delete(it) }
 
   def parsed
-    parses = Hashira::CLI::FLAGS.reject(&:page?).to_h { [it, it.read(@arguments)] }
-    Hashira::CLI::Options.new(directories: @arguments.rest, mode: mode(parses), **fields(parses))
+    parses = Hashira::CLI::FLAGS.reject(&:page?).to_h { [it, it.read(arguments)] }
+    Hashira::CLI::Options.new(directories: arguments.rest, mode: mode(parses), **fields(parses))
+      .tap { Hashira::CLI::Needs.check(it) }
   end
 
   def fields(parses) = parses.to_h { |flag, value| [flag.field, value] }.except(nil)

data/lib/hashira/cli/fail_on.rb

@@ -5,20 +5,30 @@ require_relative "../pipeline"
 module Hashira::CLI::FailOn
   MEASURES = (Hashira::Pipeline::ANALYZERS - %i[coupling smells]).map(&:to_s).freeze
 
-  KINDS = {
-    "cycles" => "cycle", "sdp" => "sdp_violation", "dupe" => "duplication",
-    **Hashira::Pipeline::STRUCTURAL.to_h { [it, it] },
-    **MEASURES.to_h { [it, it] },
-    "smells" => Hashira::Pipeline::SMELLS, **Hashira::Pipeline::SMELLS.to_h { [it, it] }
+  KINDS = { "cycles" => "cycle", "sdp" => "sdp_violation", "dupe" => "duplication" }
+    .merge(Hashira::Pipeline::STRUCTURAL.to_h { [it, it] })
+    .merge(MEASURES.to_h { [it, it] })
+    .merge("smells" => Hashira::Pipeline::SMELLS)
+    .merge(Hashira::Pipeline::SMELLS.to_h { [it, it] })
+    .freeze
+
+  OWNERS = {
+    **Hashira::Pipeline::STRUCTURAL.to_h { [it, :coupling] },
+    **MEASURES.to_h { [it, it.to_sym] },
+    **Hashira::Pipeline::SMELLS.to_h { [it, :smells] }
   }.freeze
 
   module_function
 
   def parse(list)
-    return [] unless list
-    list.split(",").flat_map { Array(kind(it.strip)) }.uniq
+    return [] if list.to_s.empty?
+    kinds = list.split(",").flat_map { Array(kind(it.strip)) }.uniq
+    raise(Hashira::Error, "--fail-on needs at least one kind") if kinds.empty?
+    kinds
   end
 
+  def owner(kind) = OWNERS.fetch(kind)
+
   def kind(name)
     KINDS.fetch(name) do
       raise(Hashira::Error, "unknown --fail-on kind #{name.inspect} (use: #{KINDS.keys.join(", ")})")

data/lib/hashira/cli/flag.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
 class Hashira::CLI
+  BLANK = %i[arg field parse mode].to_h { [it, nil] }.freeze
+
   Flag =
     Data.define(:name, :arg, :default, :field, :parse, :mode, :text) do
-      def initialize(**attributes) = super(arg: nil, default: "", field: nil, parse: nil, mode: nil, **attributes)
+      def initialize(**attributes) = super(**BLANK, default: "", **attributes)
 
       def read(arguments) = arg ? take(arguments) : arguments.delete(name)
 

data/lib/hashira/cli/flags.rb

@@ -3,8 +3,10 @@
 require_relative "fail_on"
 require_relative "flag"
 require_relative "format"
+require_relative "only"
 require_relative "package_by"
 require_relative "skip"
+require_relative "top"
 
 class Hashira::CLI
   FLAGS = [
@@ -13,6 +15,10 @@ class Hashira::CLI
       text: ["text (default), json, dot, or mermaid"]
     ),
     Flag.new(name: "--json", mode: :json, text: ["shorthand for --format json"]),
+    Flag.new(
+      name: "--compact", field: :compact,
+      text: ["emit JSON on one line, without the indentation", "meant for reading"]
+    ),
     Flag.new(
       name: "--fail-on", arg: "KINDS", field: :fail_on, parse: FailOn, mode: :fail_on,
       text: [
@@ -26,6 +32,23 @@ class Hashira::CLI
       name: "--skip", arg: "ANALYZERS", field: :skip, parse: Skip,
       text: ["drop an analyzer; comma-separated: coupling,", "complexity, duplication, smells"]
     ),
+    Flag.new(
+      name: "--only", arg: "PATHS", field: :only, parse: Only,
+      text: [
+        "keep only the findings that name these files;",
+        "comma-separated. The whole project is still read,",
+        "so cross-file signals stay right. Meant for hooks:",
+        "hashira --only $CHANGED --ratchet"
+      ]
+    ),
+    Flag.new(
+      name: "--top", arg: "N", field: :top, parse: Top,
+      text: [
+        "show at most N rows in each table and N",
+        "findings (default: 25 packages and findings,",
+        "10 methods and files)"
+      ]
+    ),
     Flag.new(
       name: "--package-by", arg: "WHAT", field: :packaging, parse: PackageBy,
       text: [

data/lib/hashira/cli/format.rb

@@ -8,6 +8,6 @@ module Hashira::CLI::Format
   def parse(value)
     return if value.empty?
     return value.to_sym if CHOICES.include?(value)
-    raise(Hashira::Error.unknown("--format", value, CHOICES))
+    raise(Hashira::CLI::Choice.unknown("--format", value, CHOICES))
   end
 end

data/lib/hashira/cli/needs.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "fail_on"
+
+module Hashira::CLI::Needs
+  DIAGRAMS = %i[dot mermaid].freeze
+
+  module_function
+
+  def check(options)
+    mode = options.mode
+    skip = options.skip
+    drawing(mode, skip)
+    gate(options.fail_on, skip)
+    shaping(options, mode)
+  end
+
+  def shaping(options, mode)
+    compacting(mode) if options.compact
+    focusing(mode) unless options.only.empty?
+  end
+
+  def focusing(mode)
+    raise(Hashira::Error, "--only narrows the findings, but --update-baseline records them all") if mode == :update
+    return unless DIAGRAMS.include?(mode)
+    raise(Hashira::Error, "--format #{mode} draws the coupling graph, which --only cannot narrow")
+  end
+
+  def compacting(mode)
+    raise(Hashira::Error, "--compact shapes JSON, but this run emits #{mode}") unless mode == :json
+  end
+
+  def drawing(mode, skip)
+    return unless DIAGRAMS.include?(mode) && skip.include?(:coupling)
+    raise(Hashira::Error, "--format #{mode} draws the coupling graph, but --skip coupling drops it")
+  end
+
+  def gate(fail_on, skip)
+    blind = fail_on.find { skip.include?(owner(it)) }
+    return unless blind
+    raise(Hashira::Error, "--fail-on #{blind} needs the #{owner(blind)} analyzer, but --skip drops it")
+  end
+
+  def owner(kind) = Hashira::CLI::FailOn.owner(kind)
+end

data/lib/hashira/cli/only.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Only
+  module_function
+
+  def parse(value)
+    return [] if value.empty?
+    value.split(",").map { vet(it.strip) }
+  end
+
+  def vet(path)
+    here = path.delete_prefix("#{Dir.pwd}/").delete_prefix("./")
+    raise(Hashira::Error, "--only #{path.inspect} is not a file here") unless File.file?(here)
+    here
+  end
+end

data/lib/hashira/cli/options.rb

@@ -2,13 +2,22 @@
 
 class Hashira::CLI
   Options =
-    Data.define(:directories, :mode, :baseline, :fail_on, :skip, :packaging) do
+    Data.define(:directories, :mode, :baseline, :fail_on, :skip, :only, :packaging, :top, :compact) do
       def self.parse(argv) = CommandLine.new(argv).options
 
-      def self.page(mode) = new(directories: [], mode:, baseline: "", fail_on: [], skip: [], packaging: :auto)
+      def self.build(mode)
+        new(
+          directories: [], baseline: "", fail_on: [], skip: [], only: [],
+          packaging: :auto, top: nil, compact: nil, mode:
+        )
+      end
 
       def pipeline
-        Hashira::Pipeline.new(Hashira::Project.detect(directories), enabled: analyzers, packaging:)
+        chosen = Hashira::Project.new(directories)
+        told = Hashira::Report::Notices.new
+        told.scanning(chosen.files.size)
+        told.rails if directories.empty? && File.exist?("config/application.rb")
+        Hashira::Pipeline.new(chosen, enabled: analyzers, packaging:, only:)
       end
 
       def analyzers = Hashira::Pipeline::ANALYZERS - skip

data/lib/hashira/cli/package_by.rb

@@ -9,6 +9,6 @@ module Hashira::CLI::PackageBy
     return :auto if value.empty?
     choice = value.to_sym
     return choice if CHOICES.include?(choice)
-    raise(Hashira::Error.unknown("--package-by", value, CHOICES))
+    raise(Hashira::CLI::Choice.unknown("--package-by", value, CHOICES))
   end
 end

data/lib/hashira/cli/run.rb

@@ -1,27 +1,39 @@
 # frozen_string_literal: true
 
 class Hashira::CLI::Run
-  MODES = { update: :update, ratchet: :check, fail_on: :guard, json: :json, dot: :diagram, mermaid: :diagram }.freeze
-
   def initialize(pipeline, options)
     @pipeline = pipeline
     @options = options
   end
 
+  MODES = { update: :update, ratchet: :check, fail_on: :guard }
+    .merge(json: :json, dot: :diagram, mermaid: :diagram).freeze
+
   def status = __send__(MODES.fetch(@options.mode, :text))
 
   private
 
   def graph = @pipeline.graph
 
-  def findings = @findings ||= Hashira::CI::Accepted.load(@options.baseline).screen(@pipeline.findings)
+  def findings = @_findings ||= accepted.screen(@pipeline.findings)
+
+  def accepted
+    path = @options.baseline
+    stop = Hashira::CI::Baseline.new(path).trouble
+    raise(Hashira::Error, stop) if stop
+    Hashira::CI::Accepted.build(path)
+  end
 
-  def update = ratchet.update
+  def update
+    ratchet.update
+  rescue SystemCallError => error
+    raise(Hashira::Error, "cannot write #{@options.baseline} (#{error.message})")
+  end
 
   def check
     stop = ratchet.blocker
     raise(Hashira::Error, stop) if stop
-    ratchet.check
+    ratchet.check(@pipeline.focus)
   end
 
   def guard = gate.check
@@ -32,9 +44,25 @@ class Hashira::CLI::Run
 
   def text = report(Hashira::Report::Text)
 
-  def report(kind) = kind.new(view).print
+  def report(kind)
+    notices
+    kind.new(view).print
+  end
+
+  def notices
+    told = Hashira::Report::Notices.new
+    told.churn(@pipeline.project.label) unless @pipeline.churn.history?
+    broken = @pipeline.unparsed
+    told.unparsed(broken.size, broken.first(3).join(", ")) unless broken.empty?
+  end
+
+  def ratchet = @_ratchet ||= Hashira::CI::Ratchet.new(graph, findings.all, baseline)
+
+  def baseline
+    Hashira::CI::Baseline.new(@options.baseline, analyzers: @options.analyzers, targets:)
+  end
 
-  def ratchet = @ratchet ||= Hashira::CI::Ratchet.new(graph, findings.all, @options.baseline)
+  def targets = @pipeline.project.directories
 
   def gate = Hashira::CI::Gate.new(findings, @options.fail_on)
 
@@ -44,7 +72,7 @@ class Hashira::CLI::Run
     Hashira::Report::View.new(
       project: @pipeline.project, graph: (graph if @pipeline.enabled?(:coupling)),
       complexity: @pipeline.complexity, duplication: @pipeline.duplication,
-      hotspots: @pipeline.hotspots, findings:
+      hotspots: @pipeline.hotspots, findings:, top: @options.top, compact: @options.compact
     )
   end
 end

data/lib/hashira/cli/top.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Hashira::CLI::Top
+  WHOLE = /\A[1-9]\d*\z/
+
+  module_function
+
+  def parse(value)
+    return if value.empty?
+    return Integer(value, 10) if value.match?(WHOLE)
+    raise(Hashira::Error, "--top #{value.inspect} is not a positive whole number")
+  end
+end

data/lib/hashira/cli/usage.rb

@@ -17,6 +17,10 @@ module Hashira::CLI::Usage
 
   FOOTER = <<~TEXT
 
+    Exit codes: 0 clean · 1 findings or a regression · 2 misuse
+    (bad flags, missing directory, unusable baseline) · 3 an
+    improvement the baseline has not recorded · 70 internal error.
+
     Findings accepted by design can be recorded in the baseline as
       "accepted": [{"kind": "...", "package": "...", "reason": "..."}]
     — they leave reports and gates, keeping a one-line reminder each.
@@ -38,7 +42,7 @@ module Hashira::CLI::Usage
   end
 
   def emit(output)
-    puts(output)
+    $stdout.puts(output)
     0
   end
 end