hashira 0.5.1 → 0.7.0

data/lib/hashira/ci/ratchet.rb

@@ -1,30 +1,53 @@
 # 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 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 +56,15 @@ class Hashira::CI::Ratchet
 
   def edges = @graph.edges.map(&:to_s)
 
-  def digests = @findings.map(&:signature).uniq.sort
+  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?
+    Hashira::CI::Diff.between(scored, @baseline.findings) if @baseline.findings?
   end
 end

data/lib/hashira/ci/ratchet_report.rb

@@ -11,7 +11,7 @@ class Hashira::CI::RatchetReport
     return unchanged if quiet?(edges, findings)
     details(edges, findings)
     advice(edges, findings)
-    1
+    verdict(edges, findings)
   end
 
   private
@@ -20,9 +20,11 @@ class Hashira::CI::RatchetReport
 
   def unchanged
     @io.puts("Ratchet OK: #{@graph.edges.size} edges, #{@findings.size} findings, unchanged.")
-    0
+    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,11 @@
+# frozen_string_literal: true
+
+module Hashira
+  module CI
+    Scope =
+      Data.define(:analyzers, :targets) do
+        def self.none = new(analyzers: [], targets: [])
+        def to_h = { analyzers: analyzers.map(&:to_s).sort, targets: targets.sort }
+      end
+  end
+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/cli/arguments.rb

@@ -9,7 +9,12 @@ class Hashira::CLI::Arguments
     position = @argv.index(flag)
     return default unless position
     _flag, value = @argv.slice!(position, 2)
-    raise(Hashira::Error, "#{flag} needs a value") unless value
+    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
 

data/lib/hashira/cli/fail_on.rb

@@ -12,13 +12,23 @@ module Hashira::CLI::FailOn
     "smells" => Hashira::Pipeline::SMELLS, **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/flags.rb

@@ -5,6 +5,7 @@ require_relative "flag"
 require_relative "format"
 require_relative "package_by"
 require_relative "skip"
+require_relative "top"
 
 class Hashira::CLI
   FLAGS = [
@@ -13,6 +14,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 +31,14 @@ class Hashira::CLI
       name: "--skip", arg: "ANALYZERS", field: :skip, parse: Skip,
       text: ["drop an analyzer; comma-separated: coupling,", "complexity, duplication, smells"]
     ),
+    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/needs.rb

@@ -0,0 +1,34 @@
+# 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(mode) if options.compact
+  end
+
+  def shaping(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/options.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
 class Hashira::CLI
+  PAGE = { directories: [], baseline: "", fail_on: [], skip: [], packaging: :auto, top: nil, compact: nil }.freeze
+
   Options =
-    Data.define(:directories, :mode, :baseline, :fail_on, :skip, :packaging) do
+    Data.define(:directories, :mode, :baseline, :fail_on, :skip, :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.page(mode) = new(**PAGE, mode:)
+
+      def initialize(**attributes)
+        super
+        Needs.check(self)
+      end
 
       def pipeline
-        Hashira::Pipeline.new(Hashira::Project.detect(directories), enabled: analyzers, packaging:)
+        chosen = Hashira::Project.detect(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:)
       end
 
       def analyzers = Hashira::Pipeline::ANALYZERS - skip

data/lib/hashira/cli/run.rb

@@ -14,9 +14,20 @@ class Hashira::CLI::Run
 
   def graph = @pipeline.graph
 
-  def findings = @findings ||= Hashira::CI::Accepted.load(@options.baseline).screen(@pipeline.findings)
+  def findings = @findings ||= accepted.screen(@pipeline.findings)
 
-  def update = ratchet.update
+  def accepted
+    path = @options.baseline
+    stop = Hashira::CI::Baseline.trouble(path)
+    raise(Hashira::Error, stop) if stop
+    Hashira::CI::Accepted.load(path)
+  end
+
+  def update
+    ratchet.update
+  rescue SystemCallError => error
+    raise(Hashira::Error, "cannot write #{@options.baseline} (#{error.message})")
+  end
 
   def check
     stop = ratchet.blocker
@@ -32,9 +43,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.load(@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 +71,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

data/lib/hashira/cli.rb

@@ -1,24 +1,43 @@
 # frozen_string_literal: true
 
 class Hashira::CLI
+  MISUSE = 2
+  BROKEN = 70
+
   def self.run(argv)
-    options = Options.parse(argv)
-    usage?(options) ? Usage.public_send(options.mode) : new(options).run
+    dispatch(Options.parse(argv))
   rescue Hashira::Error => error
     failure(error)
+  rescue StandardError => error
+    crash(error)
   end
 
+  def self.dispatch(options) = usage?(options) ? Usage.public_send(options.mode) : new(options).run
+
   def self.usage?(options) = Usage::PAGES.include?(options.mode)
 
   def self.failure(error)
-    warn("hashira: #{error.message}")
-    1
+    Kernel.warn("hashira: #{error.message}")
+    MISUSE
+  end
+
+  def self.crash(error)
+    Hashira::Report::Notices.new.crashed(error)
+    BROKEN
   end
 
   def initialize(options)
+    @started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
     @options = options
+    @notices = Hashira::Report::Notices.new
     @pipeline = options.pipeline
   end
 
-  def run = Run.new(@pipeline, @options).status
+  def run
+    Run.new(@pipeline, @options).status.tap { @notices.finished(@pipeline.project.files.size, elapsed) }
+  end
+
+  private
+
+  def elapsed = format("%.1f", Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started)
 end

data/lib/hashira/coupling/metric.rb

@@ -9,7 +9,13 @@ module Hashira
           total.zero? ? 0.0 : efferent.fdiv(total)
         end
 
-        def to_h = { tc: types, ca: afferent, ce: efferent, i: instability }
+        def isolated? = (efferent + afferent).zero?
+
+        def order = [isolated? ? 1 : 0, instability]
+
+        def to_h = { tc: types, ca: afferent, ce: efferent, i: (instability unless isolated?) }
+
+        def cells = [types, afferent, efferent, isolated? ? "—" : format("%.2f", instability)]
       end
   end
 end

data/lib/hashira/diagram/dot.rb

@@ -1,13 +1,16 @@
 # frozen_string_literal: true
 
 class Hashira::Diagram::Dot
-  def initialize(edges)
+  def initialize(edges, packages)
     @edges = edges
+    @packages = packages
   end
 
-  def source
-    "digraph hashira {\n  rankdir=LR;\n#{@edges.map do |from, to, weight|
-      %(  "#{from}" -> "#{to}" [label="#{weight}"];)
-    end.join("\n")}\n}"
-  end
+  def source = "digraph hashira {\n  rankdir=LR;\n#{lines.join("\n")}\n}"
+
+  private
+
+  def lines = @packages.map { %(  "#{it}";) } + @edges.map { |from, to, weight| link(from, to, weight) }
+
+  def link(from, to, weight) = %(  "#{from}" -> "#{to}" [label="#{weight}"];)
 end

data/lib/hashira/diagram/mermaid.rb

@@ -1,18 +1,21 @@
 # frozen_string_literal: true
 
 class Hashira::Diagram::Mermaid
-  def initialize(edges)
+  def initialize(edges, packages)
     @edges = edges
-    @nodes = {}
+    @packages = packages
+    @ids = {}
   end
 
-  def source
-    "graph LR\n#{@edges.map { |from, to, weight| "  #{node(from)} -->|#{weight}| #{node(to)}" }.join("\n")}"
-  end
+  def source = "graph LR\n#{lines.join("\n")}"
 
   private
 
-  def node(package)
-    @nodes[package] ||= "#{package.gsub(/\W/, "_")}[\"#{package}\"]"
-  end
+  def lines = @packages.map { "  #{declare(it)}" } + @edges.map { |from, to, weight| link(from, to, weight) }
+
+  def link(from, to, weight) = "  #{id(from)} -->|#{weight}| #{id(to)}"
+
+  def declare(package) = "#{id(package)}[#{package.to_json}]"
+
+  def id(package) = @ids[package] ||= "p#{@ids.size}"
 end

data/lib/hashira/diagram/source.rb

@@ -8,8 +8,11 @@ class Hashira::Diagram::Source
   end
 
   def print
-    edges = @graph.weighted
-    @io.puts((@format == :dot ? Hashira::Diagram::Dot.new(edges) : Hashira::Diagram::Mermaid.new(edges)).source)
+    @io.puts(drawing.new(@graph.weighted, @graph.packages.sort).source)
     0
   end
+
+  private
+
+  def drawing = @format == :dot ? Hashira::Diagram::Dot : Hashira::Diagram::Mermaid
 end

data/lib/hashira/pipeline.rb

@@ -9,39 +9,41 @@ class Hashira::Pipeline
 
   STRUCTURAL = Hashira::Coupling::Report::RULES.map { it::KIND }.freeze
 
-  SMELLS = Hashira::Smells::Report::CHECKS.map(&:kind).sort.freeze
+  SMELLS = (
+    Hashira::Smells::Report::CHECKS.map(&:kind) + [Hashira::Smells::BoundarySprawl::KIND]
+  ).sort.freeze
 
   def initialize(project, enabled: ANALYZERS, packaging: :auto)
     @project = project
     @enabled = enabled
-    @trees = project.files.to_h { [it, parse(it)] }
-    @coupling = Hashira::Coupling::Report.new(project, @trees, packaging: settle(packaging))
+    @parsed = Hashira::Trees.new(project)
+    @coupling = Hashira::Coupling::Report.new(project, @parsed.all, packaging: settle(packaging))
   end
 
   attr_reader :project
 
+  def unparsed = @parsed.unparsed
+
   def graph = @coupling.graph
 
-  def complexity
-    @complexity ||= Hashira::Complexity::Scores.new(@project, @trees) if enabled?(:complexity)
-  end
+  def complexity = @complexity ||= analyzed(:complexity, Hashira::Complexity::Scores)
 
-  def duplication
-    @duplication ||= Hashira::Duplication::Clones.new(@project, @trees, churn) if enabled?(:duplication)
-  end
+  def duplication = @duplication ||= analyzed(:duplication, Hashira::Duplication::Clones, churn)
 
-  def smells
-    @smells ||= Hashira::Smells::Report.new(@project, @trees) if enabled?(:smells)
-  end
+  def smells = @smells ||= analyzed(:smells, Hashira::Smells::Report)
 
   def hotspots
     @hotspots ||= Hashira::Hotspots::Rollup.new(complexity, duplication, churn) if complexity || duplication
   end
 
-  def churn = @churn ||= Hashira::Churn.scan
+  def churn = @churn ||= Hashira::Churn.scan(@project.directories.first)
 
   def enabled?(analyzer) = @enabled.include?(analyzer)
 
+  def analyzed(name, kind, *extra)
+    kind.new(@project, @parsed.all, *extra) if enabled?(name)
+  end
+
   def findings = structural + listed(complexity) + listed(duplication) + listed(smells)
 
   private
@@ -54,10 +56,4 @@ class Hashira::Pipeline
   def structural = enabled?(:coupling) ? @coupling.findings : []
 
   def listed(analyzer) = analyzer ? analyzer.findings : []
-
-  def parse(path)
-    Prism.parse_file(path).value
-  rescue SystemCallError => error
-    raise(Hashira::Error, "cannot read #{path} (#{error.message})")
-  end
 end

data/lib/hashira/project.rb

@@ -8,8 +8,8 @@ class Hashira::Project
   end
 
   def self.defaults
-    raise(Hashira::Error, "no lib/ directory here — pass the source directory explicitly") if Dir["lib/*/"].empty?
-    ["lib"]
+    return ["lib"] if Dir["lib/*/"].any? || Dir["lib/*.rb"].any?
+    raise(Hashira::Error, "no lib/ directory here — pass the source directory explicitly")
   end
   private_class_method :defaults
 
@@ -26,9 +26,9 @@ class Hashira::Project
   private_class_method :descend, :sole
 
   def initialize(directories)
-    missing = directories.reject { Dir.exist?(it) }
-    raise(Hashira::Error, "no such directory: #{missing.join(", ")}") unless missing.empty?
-    @directories = directories.map { it.delete_suffix("/") }
+    vet(directories)
+    @directories = distinct(directories.map { it.delete_suffix("/") })
+    raise(Hashira::Error, "no Ruby files under #{label}") if files.empty?
     @rails = @directories.any? { config?(File.expand_path(it)) }
   end
 
@@ -52,6 +52,20 @@ class Hashira::Project
 
   private
 
+  def vet(directories)
+    file = directories.find { File.file?(it) }
+    raise(Hashira::Error, "#{file} is a file — hashira takes directories (try: hashira #{File.dirname(file)})") if file
+    missing = directories.reject { Dir.exist?(it) }
+    raise(Hashira::Error, "no such directory: #{missing.join(", ")}") unless missing.empty?
+  end
+
+  def distinct(directories)
+    pairs = directories.map { [it, File.realpath(it)] }.uniq(&:last)
+    pairs.filter_map { |dir, path| dir unless nested?(path, pairs) }
+  end
+
+  def nested?(path, pairs) = pairs.any? { path.start_with?("#{it.last}/") }
+
   def config?(directory)
     ["config/application.rb", "../config/application.rb"].any? { File.exist?(File.expand_path(it, directory)) }
   end

data/lib/hashira/report/columns.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Hashira::Report::Columns
+  CAP = 48
+  HEAD = 23
+  GAP = "  "
+  NUMBER = /\A-?\d+(?:\.\d+)?\z/
+
+  def initialize(headers, rows, io: $stdout)
+    @headers, *@rows = [headers, *rows].map { |cells| cells.map { clip(it) } }
+    @io = io
+  end
+
+  def print
+    @io.puts(header)
+    @io.puts(rule)
+    body
+  end
+
+  def body = @rows.each { @io.puts(line(it)) }
+
+  def header = line(@headers)
+
+  def rule = "-" * [header, *@rows.map { line(it) }].map(&:length).max
+
+  private
+
+  def line(cells) = cells.map.with_index { |cell, column| pad(cell, column) }.join(GAP).rstrip
+
+  def pad(cell, column)
+    width = widths[column]
+    numeric[column] ? cell.rjust(width) : cell.ljust(width)
+  end
+
+  def widths = @widths ||= @headers.each_index.map { |column| down(column).map(&:length).max }
+
+  def numeric = @numeric ||= @headers.each_index.map { |column| @rows.any? && counted?(column) }
+
+  def counted?(column) = @rows.all? { NUMBER.match?(it[column]) }
+
+  def down(column) = [@headers[column], *@rows.map { it[column] }]
+
+  def clip(cell)
+    text = cell.to_s
+    return text if text.length <= CAP
+    "#{text[0, HEAD]}…#{text[(HEAD + 1 - CAP)..]}"
+  end
+end