hashira 0.1.0

data/lib/hashira/ci/edge_diff_report.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hashira
+  module CI
+    class EdgeDiffReport
+      def initialize(graph, io: $stdout)
+        @graph = graph
+        @io = io
+      end
+
+      def print(added, removed)
+        return print_unchanged if added.empty? && removed.empty?
+
+        print_added(added)
+        print_removed(removed)
+        1
+      end
+
+      private
+
+      def print_unchanged
+        @io.puts "Ratchet OK: #{@graph.edge_list.size} edges, unchanged."
+        0
+      end
+
+      def print_added(added)
+        return if added.empty?
+
+        added.each { print_edge(_1) }
+        @io.puts "\nRatchet FAILED. Either decouple, or if the new edge is a deliberate"
+        @io.puts "design decision, update the baseline and say why in the commit."
+      end
+
+      def print_edge(edge)
+        @io.puts "NEW EDGE #{edge} — introduced by:"
+        @graph.evidence_for(edge.from, edge.to).to_a.sort.each { @io.puts "  · #{_1}" }
+      end
+
+      def print_removed(removed)
+        return if removed.empty?
+
+        @io.puts "Edges removed (improvement!): #{removed.join(", ")}"
+        @io.puts "Lock it in: hashira --update-baseline"
+      end
+    end
+  end
+end

data/lib/hashira/ci/gate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Hashira
+  module CI
+    class Gate
+      def initialize(findings, kinds, io: $stdout)
+        @findings = findings
+        @kinds = kinds
+        @io = io
+      end
+
+      def check
+        offending = @findings.all.select { @kinds.include?(_1.kind) }
+        return report_clean if offending.empty?
+
+        offending.each { Report::FindingLines.new(_1, io: @io).print }
+        @io.puts "\nGate FAILED: #{offending.size} finding(s) of kind #{@kinds.join(", ")}."
+        1
+      end
+
+      private
+
+      def report_clean
+        @io.puts "Gate OK: no findings of kind #{@kinds.join(", ")}."
+        0
+      end
+    end
+  end
+end

data/lib/hashira/ci/ratchet.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hashira
+  module CI
+    class Ratchet
+      def initialize(graph, baseline_path, io: $stdout)
+        @graph = graph
+        @baseline_path = baseline_path
+        @io = io
+      end
+
+      SCHEMA_VERSION = 1
+
+      def update
+        edges = @graph.edge_list.map(&:to_s)
+        File.write(@baseline_path, JSON.pretty_generate(payload(edges)) << "\n")
+        @io.puts "Baseline updated: #{edges.size} edges."
+        0
+      end
+
+      def check
+        added, removed = diff(@graph.edge_list)
+        EdgeDiffReport.new(@graph, io: @io).print(added, removed)
+      end
+
+      private
+
+      def payload(edges)
+        accepted = Accepted.load(File.exist?(@baseline_path) ? @baseline_path : nil).entries
+        base = { version: SCHEMA_VERSION, edges: }
+        accepted.empty? ? base : base.merge(accepted:)
+      end
+
+      def diff(edges)
+        raise Error, "no baseline at #{@baseline_path} — run --update-baseline first" unless File.exist?(@baseline_path)
+
+        baseline = JSON.parse(File.read(@baseline_path)).fetch("edges")
+        [edges.reject { baseline.include?(_1.to_s) }, baseline - edges.map(&:to_s)]
+      end
+    end
+  end
+end

data/lib/hashira/cli/command_line.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    class CommandLine
+      DEFAULT_BASELINE = "hashira_baseline.json"
+
+      FORMATS = %w[text json dot mermaid].freeze
+
+      CI_FLAGS = { "--update-baseline" => :update_baseline, "--ratchet" => :ratchet }.freeze
+
+      def initialize(argv)
+        @arguments = argv.dup
+      end
+
+      def options = usage_options || parsed_options
+
+      private
+
+      def usage_options
+        return usage(:help) if delete("--help") || delete("-h")
+
+        usage(:version) if delete("--version")
+      end
+
+      def usage(mode) = Options.new(directories: [], mode:, baseline: nil, fail_on: [])
+
+      def parsed_options
+        values = flag_values
+        mode = parse_mode(values[:fail_on])
+        reject_unknown_flags
+        Options.new(directories: @arguments, mode:, **values)
+      end
+
+      def flag_values
+        { fail_on: FailOn.parse(take_value("--fail-on")),
+          baseline: take_value("--baseline") || DEFAULT_BASELINE }
+      end
+
+      def parse_mode(fail_on)
+        requested = requested_modes(fail_on).uniq(&:last)
+        raise Error, "conflicting options: #{requested.map(&:first).join(" and ")}" if requested.size > 1
+
+        requested.dig(0, 1) || :text
+      end
+
+      def requested_modes(fail_on)
+        ci = CI_FLAGS.filter_map { |flag, mode| [flag, mode] if delete(flag) }
+        ci + fail_on_mode(fail_on) + format_modes
+      end
+
+      def fail_on_mode(fail_on) = fail_on.empty? ? [] : [["--fail-on", :fail_on]]
+
+      def format_modes
+        format = take_format
+        modes = format ? [["--format #{format}", format.to_sym]] : []
+        delete("--json") ? modes + [["--json", :json]] : modes
+      end
+
+      def take_format
+        format = take_value("--format")
+        return format unless format
+        raise Error, "unknown --format #{format.inspect} (use: #{FORMATS.join(", ")})" unless FORMATS.include?(format)
+
+        format
+      end
+
+      def take_value(flag)
+        position = @arguments.index(flag)
+        return nil unless position
+
+        _flag, value = @arguments.slice!(position, 2)
+        raise Error, "#{flag} needs a value" unless value
+
+        value
+      end
+
+      def delete(flag) = @arguments.delete(flag)
+
+      def reject_unknown_flags
+        stray = @arguments.find { _1.start_with?("-") }
+        raise Error, "unknown option #{stray}" if stray
+      end
+    end
+  end
+end

data/lib/hashira/cli/fail_on.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    module FailOn
+      KINDS = {
+        "cycles" => "cycle", "cycle" => "cycle",
+        "sdp" => "sdp_violation", "sdp_violation" => "sdp_violation"
+      }.freeze
+
+      module_function
+
+      def parse(list)
+        return [] unless list
+
+        list.split(",").map { kind(_1.strip) }.uniq
+      end
+
+      def kind(name)
+        KINDS.fetch(name) do
+          raise Error, "unknown --fail-on kind #{name.inspect} (use: #{KINDS.keys.join(", ")})"
+        end
+      end
+    end
+  end
+end

data/lib/hashira/cli/options.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    Options = Data.define(:directories, :mode, :baseline, :fail_on) do
+      def self.parse(argv) = CommandLine.new(argv).options
+    end
+  end
+end

data/lib/hashira/cli/run.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    class Run
+      MODES = { update_baseline: :update_baseline, ratchet: :check_ratchet,
+                fail_on: :check_gate, json: :print_json,
+                dot: :print_diagram, mermaid: :print_diagram }.freeze
+
+      def initialize(pipeline, options)
+        @pipeline = pipeline
+        @options = options
+      end
+
+      def exit_code = send(MODES.fetch(@options.mode, :print_text))
+
+      private
+
+      def graph = @pipeline.graph
+
+      def ratchet = CI::Ratchet.new(graph, @options.baseline)
+
+      def update_baseline = ratchet.update
+
+      def check_ratchet = ratchet.check
+
+      def findings = @findings ||= CI::Accepted.load(@options.baseline).screen(@pipeline.findings)
+
+      def check_gate = CI::Gate.new(findings, @options.fail_on).check
+
+      def print_json = Report::Json.new(graph, findings).print
+
+      def print_diagram = Diagram::Renderer.new(graph, @options.mode).display
+
+      def print_text = Report::Text.new(@pipeline.project, graph, findings).print
+    end
+  end
+end

data/lib/hashira/cli/usage.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    module Usage
+      TEXT = <<~HELP
+        Usage: hashira [DIRECTORY ...] [options]
+
+        Package coupling metrics for Ruby, via Prism. With no directory,
+        auto-detects lib/<gem>.
+
+        Options:
+          --format FORMAT      text (default), json, dot, or mermaid
+          --json               shorthand for --format json
+          --fail-on KINDS      exit 1 if findings exist; comma-separated
+                               kinds: cycles, sdp
+          --ratchet            fail when edges appear that the baseline lacks
+          --update-baseline    write the current edge set as the baseline
+          --baseline PATH      baseline file (default: hashira_baseline.json)
+          -h, --help           print this help
+          --version            print the version
+
+        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.
+      HELP
+
+      module_function
+
+      def help = emit(TEXT)
+
+      def version = emit("hashira #{VERSION}")
+
+      def emit(output)
+        puts output
+        0
+      end
+    end
+  end
+end

data/lib/hashira/cli.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hashira
+  class CLI
+    def self.run(argv)
+      options = Options.parse(argv)
+      usage?(options) ? Usage.public_send(options.mode) : new(options).run
+    rescue Error => error
+      report_failure(error)
+    end
+
+    def self.usage?(options) = %i[help version].include?(options.mode)
+
+    def self.report_failure(error)
+      warn "hashira: #{error.message}"
+      1
+    end
+
+    def initialize(options)
+      @options = options
+      @pipeline = Pipeline.new(Project.detect(options.directories))
+    end
+
+    def run = Run.new(@pipeline, @options).exit_code
+  end
+end

data/lib/hashira/diagram/dot.rb

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

data/lib/hashira/diagram/mermaid.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Diagram
+    class Mermaid
+      def initialize(edges)
+        @edges = edges
+        @nodes = {}
+      end
+
+      def source
+        lines = @edges.map { |from, to, weight| "  #{node(from)} -->|#{weight}| #{node(to)}" }
+        "graph LR\n#{lines.join("\n")}"
+      end
+
+      private
+
+      def node(package)
+        @nodes[package] ||= "#{package.gsub(/\W/, "_")}[\"#{package}\"]"
+      end
+    end
+  end
+end

data/lib/hashira/diagram/renderer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Diagram
+    class Renderer
+      def initialize(graph, format, io: $stdout)
+        @graph = graph
+        @format = format
+        @io = io
+      end
+
+      def display
+        edges = @graph.weighted_edges
+        renderer = @format == :dot ? Dot.new(edges) : Mermaid.new(edges)
+        @io.puts renderer.source
+        0
+      end
+    end
+  end
+end

data/lib/hashira/error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hashira
+  class Error < StandardError; end
+end

data/lib/hashira/pipeline.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  class Pipeline
+    def initialize(project)
+      @project = project
+      trees = project.files.to_h { [_1, parse(_1)] }
+      @census = Analysis::Census.new(project, trees)
+      @graph = Analysis::Graph.new(project, trees, @census)
+    end
+
+    attr_reader :project, :graph
+
+    RULES = [Analysis::CycleFindings, Analysis::SdpViolationFindings].freeze
+
+    def findings = RULES.flat_map { _1.new(@project, @graph).list }
+
+    private
+
+    def parse(path)
+      Prism.parse_file(path).value
+    rescue SystemCallError => error
+      raise Error, "cannot read #{path} (#{error.message})"
+    end
+  end
+end

data/lib/hashira/project.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Hashira
+  class Project
+    ROOT_PACKAGE = "(root)"
+
+    def self.detect(directories)
+      return new(directories) unless directories.empty?
+
+      subdirectories = Dir["lib/*/"].map { File.basename(_1) }
+      raise Error, "no lib/ directory here — pass the source directory explicitly" if subdirectories.empty?
+
+      new(subdirectories.size == 1 ? ["lib/#{subdirectories.first}"] : ["lib"])
+    end
+
+    def initialize(directories)
+      missing = directories.reject { Dir.exist?(_1) }
+      raise Error, "no such directory: #{missing.join(", ")}" unless missing.empty?
+
+      @directories = directories.map { _1.delete_suffix("/") }
+    end
+
+    attr_reader :directories
+
+    def files = @directories.flat_map { Dir["#{_1}/**/*.rb"] }.sort
+
+    def package_for(path)
+      first, rest = relative(path).delete_suffix(".rb").split("/", 2)
+      rest || folder?(path, first) ? first : ROOT_PACKAGE
+    end
+
+    def relative(path) = path.delete_prefix("#{directory_of(path)}/")
+
+    def label = @directories.join(", ")
+
+    def root_package = ROOT_PACKAGE
+
+    private
+
+    def folder?(path, name) = Dir.exist?("#{directory_of(path)}/#{name}")
+
+    def directory_of(path)
+      @directories.find { path.start_with?("#{_1}/") } ||
+        raise(Error, "#{path} is outside the analyzed directories")
+    end
+  end
+end

data/lib/hashira/report/dependency_map.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Report
+    class DependencyMap
+      def initialize(graph, io: $stdout)
+        @graph = graph
+        @io = io
+      end
+
+      def print
+        @io.puts "Dependencies (DependsUpon(refs) -> | <- UsedBy):"
+        @graph.packages.sort.each { @io.puts row(_1) }
+      end
+
+      private
+
+      def row(package)
+        depends_upon = @graph.dependencies_of(package).map { "#{_1}(#{@graph.weight(package, _1)})" }.join(", ")
+        used_by = @graph.dependents_of(package).join(", ")
+        format("  %-12s -> %-32s <- %s", package,
+               depends_upon.empty? ? "(none)" : depends_upon,
+               used_by.empty? ? "(none)" : used_by)
+      end
+    end
+  end
+end

data/lib/hashira/report/finding_lines.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Report
+    class FindingLines
+      SAMPLE = 4
+
+      def initialize(finding, indent: "", io: $stdout)
+        @finding = finding
+        @indent = indent
+        @io = io
+      end
+
+      def print
+        @io.puts "#{@indent}#{@finding.kind}: #{@finding.message}"
+        @finding.evidence.first(SAMPLE).each { @io.puts "#{@indent}    · #{_1}" }
+      end
+
+      def print_with_overflow
+        print
+        overflow = @finding.evidence.size - SAMPLE
+        @io.puts "#{@indent}    · … (#{overflow} more)" if overflow.positive?
+      end
+    end
+  end
+end

data/lib/hashira/report/json.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hashira
+  module Report
+    class Json
+      def initialize(graph, findings, io: $stdout)
+        @graph = graph
+        @findings = findings
+        @io = io
+      end
+
+      def print
+        @io.puts JSON.pretty_generate(packages:, edges:, findings: @findings.all.map(&:to_h),
+                                      accepted: accepted_entries)
+        0
+      end
+
+      private
+
+      def accepted_entries
+        @findings.accepted.map { |finding, reason| finding.to_h.merge(reason:) }
+      end
+
+      def packages
+        @graph.metrics.sort_by { |_package, metric| metric.instability }
+                      .to_h do |package, metric|
+          [package,
+           metric.to_h.merge(cyclic: @graph.cyclic?(package))]
+        end
+      end
+
+      def edges
+        @graph.weighted_edges.map do |from, to, weight|
+          { from:, to:, weight:, refs: @graph.evidence_for(from, to).to_a.sort }
+        end
+      end
+    end
+  end
+end

data/lib/hashira/report/metrics_table.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Report
+    class MetricsTable
+      def initialize(graph, io: $stdout)
+        @graph = graph
+        @io = io
+      end
+
+      def print
+        heading
+        by_instability.each { |package, metric| @io.puts row(package, metric) }
+        legend
+      end
+
+      private
+
+      def by_instability = @graph.metrics.sort_by { |_package, metric| metric.instability }
+
+      def heading
+        @io.puts format("%-12s %3s %3s %3s %5s  %-3s", *%w[package TC Ca Ce I Cyc])
+        @io.puts "-" * 40
+      end
+
+      def row(package, metric)
+        cyclic = @graph.cyclic?(package) ? "YES" : "-"
+        format("%-12s %3d %3d %3d %5.2f  %-3s", package,
+               metric.type_count, metric.afferent, metric.efferent, metric.instability, cyclic)
+      end
+
+      def legend
+        @io.puts "\nLegend: TC total types, Ca afferent (incoming), Ce efferent (outgoing),"
+        @io.puts "        I=Ce/(Ce+Ca) instability (0=maximally stable, 1=maximally unstable)\n\n"
+      end
+    end
+  end
+end

data/lib/hashira/report/text.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Report
+    class Text
+      def initialize(project, graph, findings, io: $stdout)
+        @project = project
+        @graph = graph
+        @findings = findings
+        @io = io
+      end
+
+      def print
+        header
+        MetricsTable.new(@graph, io: @io).print
+        DependencyMap.new(@graph, io: @io).print
+        findings_section
+        0
+      end
+
+      private
+
+      def header
+        packages = @graph.packages.size
+        @io.puts "Package (layer) metrics for #{@project.label}  " \
+                 "(#{packages} packages, #{@project.files.size} files)\n\n"
+        single_package_note if packages == 1
+      end
+
+      def single_package_note
+        @io.puts "Only one package found — there are no boundaries to analyze. " \
+                 "Pass subdirectories to set them (e.g. hashira lib/gem/*/).\n\n"
+      end
+
+      def findings_section
+        all = @findings.all
+        @io.puts "\nFindings (#{all.size}):"
+        print_findings(all)
+        accepted_section
+        @io.puts "\n  Full evidence + machine format: hashira --json" unless all.empty?
+      end
+
+      def print_findings(all)
+        return @io.puts "  none ✓ — structure is healthy" if all.empty?
+
+        all.each { FindingLines.new(_1, indent: "  ", io: @io).print_with_overflow }
+      end
+
+      def accepted_section
+        accepted = @findings.accepted
+        return if accepted.empty?
+
+        @io.puts "\nAccepted (#{accepted.size}):"
+        accepted.each { |finding, reason| @io.puts "  ~ #{finding.kind}/#{finding.package} — #{reason}" }
+      end
+    end
+  end
+end