hashira 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9641685509b4a0fa17ee87a9e29f56906f7ea487622185f935b3a544c9f214bf
+  data.tar.gz: a2e3e7da103a76e5dd080402c15eb8a3b83ebae1b1d5047303e0a33971fcc203
+SHA512:
+  metadata.gz: bef9ad9240fdfc1631211b46f87a7d1da6cbb826f4b5b0fabcd8957432915229d85f1d68463fb2c0fef67d8a61d561acadbcba8a14db87b3c8d8b55036d36f7b
+  data.tar.gz: e8ac4c4da5da2a53415bb16e64599387ccf815e679e767c8b16fcd8200ce2f4f3bcae5c48439d9d480388b657e7c02b16d4c1e258b9a62037f471a40518da278

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-07-19
+
+### Added
+
+- Package (layer) metrics from the AST via Prism: TC, Ca, Ce, instability, cycles.
+- Plain-English findings with file-level evidence, each stating something
+  provable from the AST: cycles and SDP violations.
+- CI gate (`--fail-on cycles,sdp`) and edge-set ratchet (`--ratchet`,
+  `--update-baseline`), with accepted-by-design findings recorded in the
+  baseline.
+- Output formats: text, JSON, Graphviz dot, Mermaid (`--format`, `--json`).
+- `--help` and `--version`.
+
+[0.1.0]: https://github.com/giacope/hashira/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Giacomo GK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,98 @@
+# hashira
+
+:classical_building: Package coupling metrics for Ruby, read from the AST via Prism.
+
+## Installation
+
+```ruby
+gem "hashira"
+```
+
+Requires Ruby 3.4+.
+
+## Getting Started
+
+```sh
+hashira                  # auto-detects lib/<gem>
+hashira lib/myapp        # or point it at a directory
+hashira app lib          # or several — one shared graph
+```
+
+You get a report like:
+
+```
+package       TC  Ca  Ce     I  Cyc
+----------------------------------------
+analysis      20   1   0  0.00  -
+report         7   2   0  0.00  -
+ci             4   1   2  0.67  -
+cli            6   0   4  1.00  -
+```
+
+## How to Read the Numbers
+
+Every folder under the target directory is a **package**. For each one:
+
+- **TC** — how many classes/modules it defines.
+- **Ca** — how many packages depend *on* it (afferent, incoming).
+- **Ce** — how many packages it depends *upon* (efferent, outgoing).
+- **I** — instability, `Ce / (Ce + Ca)`, from 0 to 1.
+
+**I = 0**: everyone depends on it, it depends on no one — a foundation, expensive to change. **I = 1**: nobody depends on it — free to change. Neither is good or bad on its own; a CLI layer *should* be at 1.00, a core domain layer near 0.00. The findings are about arrows pointing the wrong way:
+
+- **SDP violation** — a stable package depends on a less stable one.
+- **Cycle** — packages depending on each other in a loop.
+
+Each finding comes with file-level evidence; for cycles, the shortest cycle path and its lightest edge. What a finding means for your design is your call.
+
+## How It Works
+
+A dependency edge A→B exists when a file in package A references a constant declared by package B. Declarations are read from the AST; strings and comments are invisible. A type counts toward TC only if it defines a method directly in its body — pure namespace wrappers don't count. The root namespace is inferred (the most common outermost constant), so `App::Alpha` and `Alpha` resolve to the same package.
+
+Each edge carries a **weight**: the number of constant references backing it. A root-level file `x.rb` folds into package `x` when a sibling folder `x/` exists; everything else at the top level lands in `(root)`.
+
+## CI
+
+Fail the build when specific finding kinds exist:
+
+```sh
+hashira --fail-on cycles,sdp     # kinds: cycles, sdp
+```
+
+Or ratchet: commit a baseline and only allow the edge set to shrink. New edges fail with the evidence that introduced them.
+
+```sh
+hashira --ratchet                # compares against hashira_baseline.json
+hashira --update-baseline        # lock in improvements
+hashira --ratchet --baseline PATH
+```
+
+Findings accepted by design can be recorded in the baseline with a reason — they leave reports and gates, keeping a one-line reminder each:
+
+```json
+"accepted": [
+  {"kind": "sdp_violation", "package": "models", "reason": "config is generated, churn is harmless"}
+]
+```
+
+## Other Formats
+
+```sh
+hashira --json            # machine format with full evidence + edge weights
+hashira --format dot      # Graphviz digraph
+hashira --format mermaid  # Mermaid diagram
+```
+
+## Why No A, D, or Zones
+
+Classic package-metrics tools also measure abstractness (A), distance-from-main-sequence (D), and the Pain/Uselessness zones. Those assume formal interfaces are how you decouple. Idiomatic Ruby decouples via duck typing, so any abstractness proxy pins to ~0 and the "zone" verdict just restates I. Deliberately skipped.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/giacope/hashira](https://github.com/giacope/hashira). See
+[CONTRIBUTING.md](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[MIT](LICENSE.txt)

data/exe/hashira

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "hashira"
+
+exit Hashira::CLI.run(ARGV)

data/lib/hashira/analysis/census.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class Census
+      def initialize(project, trees)
+        @definitions = Definitions.new(project, trees)
+        @type_count = Hash.new(0)
+        @declaring_package = {}
+        @root_namespace = RootNamespace.infer(@definitions)
+        take
+      end
+
+      attr_reader :type_count, :declaring_package, :root_namespace
+
+      def packages = (@type_count.keys | @definitions.packages)
+
+      def resolve(segments)
+        outer, inner = segments.first(2)
+        @declaring_package[outer == root_namespace ? inner : outer]
+      end
+
+      private
+
+      def take
+        @definitions.each do |node, full, package|
+          register(full, package)
+          @type_count[package] += 1 unless Syntax.direct_definitions(node).empty?
+        end
+      end
+
+      # Assumes each top-level name is declared by one package; if two
+      # packages declare the same name, the last file (in sort order) wins.
+      def register(full, package)
+        outer, inner = full.first(2)
+        name = outer == root_namespace ? inner : outer
+        @declaring_package[name] = package if name
+      end
+    end
+  end
+end

data/lib/hashira/analysis/cycle_findings.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class CycleFindings < Rule
+      KIND = "cycle"
+
+      def list
+        graph.packages.select { graph.cyclic?(_1) }.sort.map { cycle_finding(_1) }
+      end
+
+      private
+
+      def cycle_finding(package)
+        path = graph.cycle_path(package)
+        finding(package:, cycle: path, evidence: evidence(path),
+                message: message(package, path, graph.weakest_edge(path)))
+      end
+
+      def message(package, path, weak_edge)
+        weak_from, weak_to = weak_edge
+        weight = graph.weight(weak_from, weak_to)
+        "#{package} can reach itself: #{path.join(" -> ")} — any change may ripple back " \
+          "around. The lightest edge on this cycle is #{weak_from} -> #{weak_to} " \
+          "(#{weight} ref#{"s" unless weight == 1})."
+      end
+
+      def evidence(path)
+        path.each_cons(2).flat_map { |from, to| graph.evidence_for(from, to).to_a.first(2) }
+      end
+    end
+  end
+end

data/lib/hashira/analysis/cycle_search.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class CycleSearch
+      def initialize(dependencies, package)
+        @dependencies = dependencies
+        @package = package
+        @predecessor = {}
+        @queue = dependencies[package].to_a.each { @predecessor[_1] = package }
+      end
+
+      def path
+        trace_back([@package]) if cycle?
+      end
+
+      private
+
+      def cycle?
+        while (node = @queue.shift)
+          return true if node == @package
+
+          visit(node)
+        end
+      end
+
+      def visit(node)
+        @dependencies[node].each do |neighbor|
+          next if @predecessor.key?(neighbor)
+
+          @predecessor[neighbor] = node
+          @queue << neighbor
+        end
+      end
+
+      def trace_back(path)
+        first = path.first
+        return path if first == @package && path.size > 1
+
+        trace_back(path.unshift(@predecessor[first]))
+      end
+    end
+  end
+end

data/lib/hashira/analysis/definitions.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class Definitions
+      include Enumerable
+
+      def initialize(project, trees)
+        @project = project
+        @trees = trees
+      end
+
+      def each(&)
+        @trees.each { |file, tree| definitions_in(file, tree, &) }
+      end
+
+      def packages = @trees.keys.map { @project.package_for(_1) }.uniq
+
+      private
+
+      def definitions_in(file, tree)
+        package = @project.package_for(file)
+        TypeWalk.each_definition(tree) { |node, full| yield node, full, package }
+      end
+    end
+  end
+end

data/lib/hashira/analysis/edge.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    Edge = Data.define(:from, :to) do
+      def to_s = "#{from} -> #{to}"
+    end
+  end
+end

data/lib/hashira/analysis/edge_map.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class EdgeMap
+      def initialize(project, census)
+        @project = project
+        @census = census
+        @dependencies = empty_sets
+        @evidence = empty_sets
+      end
+
+      attr_reader :dependencies, :evidence
+
+      def record(file, tree)
+        from = @project.package_for(file)
+        source = @project.relative(file)
+        References.each_sighting(tree).each do |segments, line|
+          record_reference(from, source, segments, line)
+        end
+      end
+
+      private
+
+      def empty_sets = Hash.new { |hash, key| hash[key] = Set.new }
+
+      def record_reference(from, source, segments, line)
+        to = @census.resolve(segments)
+        return unless to && to != from
+
+        @dependencies[from] << to
+        @evidence[[from, to]] << "#{source}:#{line}: #{segments.join("::")}"
+      end
+    end
+  end
+end

data/lib/hashira/analysis/finding.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    Finding = Data.define(:kind, :package, :message, :evidence, :cycle) do
+      def initialize(cycle: nil, **rest) = super
+
+      def to_h = super.compact
+    end
+  end
+end

data/lib/hashira/analysis/graph.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class Graph
+      def initialize(project, trees, census)
+        @census = census
+        @edge_map = EdgeMap.new(project, census)
+        trees.each { |file, tree| @edge_map.record(file, tree) }
+      end
+
+      def packages = @census.packages
+
+      def dependencies_of(package) = dependencies[package].to_a.sort
+
+      def dependents_of(package) = packages.select { dependencies[_1].include?(package) }.sort
+
+      def edge_list
+        dependencies.sort.flat_map { |from, tos| tos.sort.map { Edge.new(from:, to: _1) } }
+      end
+
+      def weighted_edges
+        edge_list.map do |edge|
+          from, to = edge.deconstruct
+          [from, to, weight(from, to)]
+        end
+      end
+
+      def evidence_for(from, to) = @edge_map.evidence[[from, to]]
+
+      def metric_for(package)
+        Metric.new(type_count: @census.type_count[package],
+                   afferent: dependents_of(package).size,
+                   efferent: dependencies[package].size)
+      end
+
+      def metrics = packages.to_h { [_1, metric_for(_1)] }
+
+      def sdp_violations = SdpCheck.new(dependencies, metrics).violations
+
+      def cyclic?(package) = !!cycle_path(package)
+
+      def weight(from, to) = evidence_for(from, to).size
+
+      def cycle_path(package) = CycleSearch.new(dependencies, package).path
+
+      def weakest_edge(path)
+        path.each_cons(2).min_by { |from, to| weight(from, to) }
+      end
+
+      private
+
+      def dependencies = @edge_map.dependencies
+    end
+  end
+end

data/lib/hashira/analysis/metric.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    Metric = Data.define(:type_count, :afferent, :efferent) do
+      def instability
+        total = efferent + afferent
+        total.zero? ? 0.0 : efferent.to_f / total
+      end
+
+      def to_h = { tc: type_count, ca: afferent, ce: efferent, i: instability }
+    end
+  end
+end

data/lib/hashira/analysis/node_walk.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    module NodeWalk
+      module_function
+
+      def each_node(node, &)
+        yield(node)
+        node.compact_child_nodes.each { each_node(_1, &) }
+      end
+    end
+  end
+end

data/lib/hashira/analysis/references.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  module Analysis
+    module References
+      module_function
+
+      def list(tree)
+        each_sighting(tree).map(&:first)
+      end
+
+      def each_sighting(tree)
+        [].tap { collect(tree, _1) }
+      end
+
+      def collect(node, accumulator)
+        return unless node
+        return accumulator << [Syntax.path_segments(node), node.location.start_line] if constant?(node)
+
+        branches(node).each { collect(_1, accumulator) }
+      end
+
+      def constant?(node) = node.is_a?(Prism::ConstantPathNode) || node.is_a?(Prism::ConstantReadNode)
+
+      def branches(node)
+        definition?(node) ? definition_branches(node) : node.compact_child_nodes
+      end
+
+      def definition?(node) = node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+
+      def definition_branches(node)
+        superclass = node.is_a?(Prism::ClassNode) ? node.superclass : nil
+        [superclass, node.body]
+      end
+    end
+  end
+end

data/lib/hashira/analysis/root_namespace.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    module RootNamespace
+      module_function
+
+      def infer(definitions)
+        definitions.map { |_node, full, _package| full.first }
+                   .tally.max_by { |_name, count| count }&.first
+      end
+    end
+  end
+end

data/lib/hashira/analysis/rule.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class Rule
+      def initialize(project, graph)
+        @project = project
+        @graph = graph
+      end
+
+      private
+
+      attr_reader :project, :graph
+
+      def metrics = @metrics ||= graph.metrics
+
+      def finding(**attributes)
+        Finding.new(kind: self.class::KIND, cycle: nil, **attributes)
+      end
+    end
+  end
+end

data/lib/hashira/analysis/sdp_check.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class SdpCheck
+      def initialize(dependencies, metrics)
+        @dependencies = dependencies
+        @metrics = metrics
+      end
+
+      def violations
+        @dependencies.flat_map do |from, tos|
+          tos.select { @metrics[_1].instability > @metrics[from].instability }.map { [from, _1] }
+        end
+      end
+    end
+  end
+end

data/lib/hashira/analysis/sdp_violation_findings.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Hashira
+  module Analysis
+    class SdpViolationFindings < Rule
+      KIND = "sdp_violation"
+
+      def list
+        graph.sdp_violations.sort_by { |from, to| instability(from) - instability(to) }
+                            .map { |from, to| violation_finding(from, to) }
+      end
+
+      private
+
+      def violation_finding(from, to)
+        finding(package: from, evidence: graph.evidence_for(from, to).to_a.first(5),
+                message: "#{from} (I=#{label(from)}) depends on the LESS stable #{to} " \
+                         "(I=#{label(to)}) — churn in #{to} will force churn in #{from}. " \
+                         "Invert the edge or extract the stable part of #{to} that #{from} needs.")
+      end
+
+      def instability(package) = metrics[package].instability
+
+      def label(package) = format("%.2f", instability(package))
+    end
+  end
+end

data/lib/hashira/analysis/syntax.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  module Analysis
+    module Syntax
+      module_function
+
+      def path_segments(node)
+        case node
+        when Prism::ConstantReadNode then [node.name.to_s]
+        when Prism::ConstantPathNode then path_segments(node.parent) + name_of(node)
+        else []
+        end
+      end
+
+      def name_of(node) = [node.name.to_s]
+
+      def direct_definitions(type_node)
+        body = type_node.body
+        statements = body.is_a?(Prism::StatementsNode) ? body.body : [body]
+        statements.grep(Prism::DefNode)
+      end
+    end
+  end
+end

data/lib/hashira/analysis/type_walk.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  module Analysis
+    module TypeWalk
+      module_function
+
+      def each_definition(node, prefix = [], &)
+        return each_child_definition(node, prefix, &) unless type_node?(node)
+
+        full = prefix + Syntax.path_segments(node.constant_path)
+        yield(node, full)
+        each_child_definition(node.body, full, &)
+      end
+
+      def type_node?(node) = node.is_a?(Prism::ClassNode) || node.is_a?(Prism::ModuleNode)
+
+      def each_child_definition(node, prefix, &)
+        children = node ? node.compact_child_nodes : []
+        children.each { each_definition(_1, prefix, &) }
+      end
+    end
+  end
+end

data/lib/hashira/ci/accepted.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hashira
+  module CI
+    class Accepted
+      Screened = Data.define(:all, :accepted)
+
+      Entry = Data.define(:kind, :package, :reason) do
+        def self.from(hash) = new(kind: hash["kind"], package: hash["package"], reason: hash["reason"])
+
+        def matches?(finding) = [kind, package] == [finding.kind, finding.package]
+
+        def label = reason || "accepted (no reason recorded)"
+
+        def to_h = { kind:, package:, reason: }.compact
+      end
+
+      def self.load(path)
+        return new([]) unless path && File.exist?(path)
+
+        new(JSON.parse(File.read(path)).fetch("accepted", []))
+      end
+
+      def initialize(entries)
+        @entries = entries.map { Entry.from(_1) }
+      end
+
+      def entries = @entries.map(&:to_h)
+
+      def screen(findings)
+        accepted, live = findings.map { [_1, reason_for(_1)] }.partition(&:last)
+        Screened.new(all: live.map(&:first), accepted:)
+      end
+
+      private
+
+      def reason_for(finding)
+        @entries.find { _1.matches?(finding) }&.label
+      end
+    end
+  end
+end