hashira 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b806d4d5704515b3371235d38cdd4e60a0c37b98194c91922d57a8f5c448ffab
-  data.tar.gz: 774766f13fa3b820557cb613e9d9b0c7ffcca2d220c30611562d1467a21f142b
+  metadata.gz: 2e10a9ee1cb16f2b8090dfe962aaa9b8c0fc7b2bf598f507c31817cc6a4a334b
+  data.tar.gz: 88e97bb9d5a8b524928014aa2248c917dff0fa3d9a19e785cc2477a40341204c
 SHA512:
-  metadata.gz: 8bd5fc6feb807c1255adec14ee18405842a7125dbb4d661c777f85454a831f357484090d90ef39cdc2e1d854df037f61147ede6ef1dfa1854b945bfbb27cd686
-  data.tar.gz: c853f3b158e0a1e501aeb48333c793eb92fcf0e51c9dabbdd538e643889dfd36141c1bfacfcd8bbebc03934cb0ec96690508cd7747cea99fb4b3e081b1aca4b9
+  metadata.gz: 332e29ec2e0841e9ee3476e9155d707b00b97ec116fd88a578bd3b38d4aa2f169cb2cd1dcb531fb9e22ba6909893559463f0282f151b0815f76729efd4e913fb
+  data.tar.gz: 2ab5337504ff4390112874e55cc661970b94d3638b79ad93900d0d2c642eaa2cdcfdd9e9acd21eb80bca0e5371585fa7a1ea0a6e7ed8512df60dfbc087b397cd

data/CHANGELOG.md

@@ -5,6 +5,102 @@ 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.4.0] - 2026-08-02
+
+### Added
+
+- Rails awareness. A directory with `config/application.rb` inside it (the
+  Rails root) or beside it (its `app` folder) is detected as a Rails app:
+  coupling defaults to namespace packaging, and under namespace packaging
+  references to app-defined `Application*` base classes (`ApplicationRecord`,
+  `ApplicationJob`, `ApplicationSerializer`, `ApplicationPolicy`, …) are
+  skipped as framework plumbing. An explicit `--package-by folder` keeps the
+  full legacy edge set, `Application*` references included.
+- Baselines record their packaging mode (schema v3; older baselines read as
+  folder). `--ratchet` refuses a baseline recorded under another mode with
+  instructions to rerun with `--package-by <recorded>` or refresh via
+  `--update-baseline`, instead of failing every edge as drift after the
+  Rails default flips packaging.
+- `--package-by folder|namespace`. Namespace packaging groups types by
+  top-level constant (`Billing`, `Ci`, `User`) across layer folders, so the
+  coupling tables and findings answer the domain question — does `Billing`
+  reach into `Ci`? — instead of restating Rails layout (`models -> jobs`).
+  Folder packaging stays the default outside Rails and remains available
+  everywhere via the flag.
+
+### Changed
+
+- **Breaking (Ruby API only; the CLI is unchanged.)** Names throughout the
+  library are now single-word, following rubocop-elegant: `Graph#dependents_of`
+  is `#incoming`, `Graph#edge_list` is `#edges`, `Project#package_for` is
+  `#package`, `Churn.from_git` is `Churn.scan`, and `Similarity#at_least?` is
+  `#meets?`. Cycle queries moved off `Graph` onto `Graph#cycles`:
+  `graph.cyclic?(p)`, `graph.cycle(p)`, and `graph.weakest(path)` are now
+  `graph.cycles.through?(p)`, `graph.cycles.path(p)`, and
+  `graph.cycles.weakest(path)`.
+- One cycle finding per distinct loop, reported from its smallest member,
+  instead of one per participating package.
+- Under namespace packaging, a top-level class that anchors no namespace of
+  its own and inherits from an app-defined class folds into its base's
+  package, transitively — a flat family of notification subclasses reports
+  as one package, not twenty.
+- Past 25 rows, the metrics table hides single-type packages with no
+  outgoing edges and at most one incoming behind a count line; they stay in
+  the graph, so their afferent weight still counts. A heavily depended-upon
+  package (high Ca) always keeps its row — its stability is the point of
+  the table.
+- Under namespace packaging in a Rails app, a singleton class named by
+  convention (`SandboxResource`, `UserSerializer`, `AccountPolicy`,
+  `PlanDecorator`) folds into its domain's package when that package exists;
+  an app-defined superclass still takes precedence over the name.
+- Every fold is disclosed: a `Folded` list under the coupling tables and a
+  `folds` array in `--json`, each entry naming the fold and whether it came
+  from a base class or a naming suffix.
+- Classes count toward TC even when their body is pure DSL (Alba resources,
+  notifiers); only modules still need a directly defined method.
+
+### Fixed
+
+- References into `Application*` namespaces (`ApplicationCable::Channel`)
+  are skipped in Rails apps like the bases themselves, and no longer pull
+  channels into a plumbing package.
+- A proper prefix of a reference only matches exact definition paths: with
+  an app-defined `Billing::Stripe`, the gem constant `Stripe::RateLimitError`
+  no longer resolves to `Billing` when `RateLimitError` is unknown.
+  Whole-reference suffix shorthand is untouched.
+- Constants resolve through their lexical nesting, like Ruby. A bare
+  `Authentication` inside `class User` now resolves to `User::Authentication`
+  before a top-level `Authentication` in another package, superclasses
+  resolve in the enclosing scope (but are charged to the class they define),
+  and a scoped hit claimed by several packages resolves to nothing rather
+  than falling through to a namesake. Kills phantom cross-package edges in
+  Rails apps, where nested concerns routinely shadow top-level names.
+- `::`-anchored references resolve at top level only, like Ruby: `::User`
+  inside `module Admin` binds to the top-level `User`, never a nested
+  `Admin::User` namesake.
+- A constant under a namespaced class (`Invoice::STATES` with
+  `Admin::Invoice` defined, referenced inside `Admin`) resolves through the
+  enclosing scope by longest registered prefix, so the edge to the class's
+  package is kept.
+- A compact reopen (`class Foo::Bar` inside `module Baz`) anchors its root
+  like Ruby — innermost enclosing scope that defines it, else top level —
+  so its types and references are charged to `Foo`, not `Baz`.
+- A class reopened across files counts once toward TC, and a lone subclass
+  reopened in a later-sorting file keeps its base fold; fold results no
+  longer depend on file order.
+- Mutually-linked folds (a base fold one way, a suffix fold the other)
+  merge into one package instead of swapping the two packages' identities,
+  and a fold link from a package to itself is dropped instead of being
+  disclosed as `X -> X`.
+- A superclass resolves only against registered definition paths: a bare
+  `Base` no longer folds its subclass into an unrelated `Admin::Base`
+  matched by suffix shorthand.
+- Namespace-prefix inference votes with every distinct definition path and
+  requires a wrapper to enclose all of them, so a domain namespace sharing
+  a single folder with top-level classes is kept as a package instead of
+  being stripped as a gem wrapper.
+- `--package-by auto` is accepted as the explicit spelling of the default.
+
 ## [0.3.0] - 2026-07-26
 
 ### Changed
@@ -113,6 +209,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Output formats: text, JSON, Graphviz dot, Mermaid (`--format`, `--json`).
 - `--help` and `--version`.
 
+[0.4.0]: https://github.com/giacope/hashira/releases/tag/v0.4.0
 [0.3.0]: https://github.com/giacope/hashira/releases/tag/v0.3.0
 [0.2.0]: https://github.com/giacope/hashira/releases/tag/v0.2.0
 [0.1.0]: https://github.com/giacope/hashira/releases/tag/v0.1.0

data/README.md

@@ -39,7 +39,7 @@ A healthy project reports `Findings (0): none ✓ — structure is healthy`.
 
 ## Contents
 
-[Install](#install) · [Getting started](#getting-started) · [Coupling: how to read the numbers](#coupling-how-to-read-the-numbers) · [Cognitive complexity](#cognitive-complexity) · [Duplication](#duplication) · [Hotspots](#hotspots) · [How it works](#how-it-works) · [CI](#ci) · [Other formats](#other-formats) · [Why cognitive complexity](#why-cognitive-complexity) · [Why no A, D, or zones](#why-no-a-d-or-zones)
+[Install](#install) · [Getting started](#getting-started) · [Coupling: how to read the numbers](#coupling-how-to-read-the-numbers) · [Rails apps](#rails-apps) · [Cognitive complexity](#cognitive-complexity) · [Duplication](#duplication) · [Hotspots](#hotspots) · [How it works](#how-it-works) · [CI](#ci) · [Other formats](#other-formats) · [Why cognitive complexity](#why-cognitive-complexity) · [Why no A, D, or zones](#why-no-a-d-or-zones)
 
 ## Install
 
@@ -158,6 +158,47 @@ domain layer near 0.00. The findings are about arrows pointing the wrong way:
 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.
 
+## Rails apps
+
+Rails layer folders are framework layout, not architecture: models will always
+touch jobs and mailers, so folder packages under `app/` report idioms as
+findings. When the analyzed directory contains a `config/application.rb` (the
+Rails root) or sits beside one (its `app` folder), hashira switches to
+**namespace packaging**: types group by top-level constant
+(`Billing`, `Ci`, `User`) across the layer folders, edges join domains, and the
+findings answer the question a Rails monolith actually has — does `Billing`
+reach into `Ci`?
+
+```console
+$ hashira app
+package       TC  Ca  Ce     I  Cyc
+----------------------------------------
+Account       26  21  18  0.46  YES
+Billing      116  12  11  0.48  YES
+Ci           107   9  16  0.64  YES
+...
+  cycle: Account can reach itself: Account -> User -> Account — any change
+  may ripple back around. The lightest edge on this cycle is Account -> User (1 ref).
+      · models/account.rb:36: User
+      · models/user/signup.rb:32: Account
+```
+
+Under namespace packaging, references to app-defined `Application*` base
+classes (`ApplicationRecord`, `ApplicationJob`, …) are skipped as framework
+plumbing; `--package-by folder` keeps them, so the legacy layer view stays
+complete. Constant resolution
+follows Ruby's lexical nesting everywhere — a bare `Authentication` inside
+`class User` is `User::Authentication`, not a top-level namesake in another
+package — which matters most in Rails apps, where nested concerns routinely
+shadow top-level names.
+
+Either grouping can be forced anywhere:
+
+```sh
+hashira app --package-by folder      # layer view, even in a Rails app
+hashira lib/gem --package-by namespace
+```
+
 ## Cognitive complexity
 
 hashira scores every method with **cognitive complexity**, not an ABC or call-count

data/lib/hashira/analysis/catalog.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Hashira::Analysis::Catalog
+  include Enumerable
+
+  def initialize(definitions)
+    @definitions = definitions
+    @naming = Hashira::Analysis::Naming.new(definitions)
+    @entries = definitions.map { |node, full, folder| entry(node, full, folder) }
+  end
+
+  def each(&) = @entries.each(&)
+
+  def prefix = @naming.segments
+
+  def strip(path) = @naming.strip(path)
+
+  def roots = @definitions.roots
+
+  def folders = @definitions.packages
+
+  private
+
+  def entry(node, full, folder)
+    Hashira::Analysis::Definition.new(node:, path: @naming.strip(full), folder:)
+  end
+end

data/lib/hashira/analysis/census.rb

@@ -1,39 +1,46 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Analysis
-    class Census
-      def initialize(project, trees)
-        @definitions = Definitions.new(project, trees)
-        @type_count = Hash.new(0)
-        @registry = ConstantRegistry.new
-        @namespace_prefix = NamespacePrefix.infer(@definitions)
-        take
-      end
+class Hashira::Analysis::Census
+  def initialize(project, trees, packaging: :folder)
+    @catalog = Hashira::Analysis::Catalog.new(Hashira::Analysis::Definitions.new(project, trees))
+    @placement = Hashira::Analysis::Placement.build(packaging, project, @catalog)
+    @folding = Hashira::Analysis::NoFolding
+    @roster = tally
+    settle
+  end
+
+  def packaging = @placement.mode
+
+  def types = @roster.types
+
+  def prefix = @catalog.prefix
+
+  def origins = @roster.origins
 
-      attr_reader :type_count, :namespace_prefix
+  def roots = @catalog.roots
 
-      def declaring_package = @registry.declaring_package
+  def packages = @roster.packages | @placement.baseline
 
-      def packages = (@type_count.keys | @definitions.packages)
+  def folds = @folding.disclosed
 
-      def resolve(segments) = @registry.package_for(after_prefix(segments))
+  def resolve(segments, nesting = []) = resolver.resolve(segments, nesting)
 
-      private
+  def pinpoint(segments) = resolver.pinpoint(segments)
 
-      def take
-        @definitions.each do |node, full, package|
-          @registry.register(after_prefix(full), package)
-          @type_count[package] += 1 unless Syntax.direct_definitions(node).empty?
-        end
-      end
+  def charge(file, nesting) = translate(@placement.charge(file, nesting))
 
-      def after_prefix(segments)
-        return [] if @namespace_prefix.first(segments.length) == segments
+  private
 
-        depth = @namespace_prefix.length.downto(0).find { segments.first(it) == @namespace_prefix.last(it) }
-        segments.drop(depth)
-      end
-    end
+  def tally
+    Hashira::Analysis::Roster.new(@placement.placed.map { |definition, package| [definition, translate(package)] })
   end
+
+  def settle
+    @folding = @placement.folding(self)
+    @roster = tally unless @folding.map.empty?
+  end
+
+  def translate(package) = @folding.map.fetch(package, package)
+
+  def resolver = Hashira::Analysis::Resolver.new(@roster.registry, @catalog, @placement)
 end

data/lib/hashira/analysis/constant_registry.rb

@@ -1,40 +1,43 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Analysis
-    class ConstantRegistry
-      AMBIGUOUS = Object.new.freeze
-
-      def initialize
-        @declaring_package = {}
-        @shorthand = {}
-      end
-
-      attr_reader :declaring_package
-
-      def register(path, package)
-        return if path.empty?
-
-        claim(@declaring_package, path, package)
-        (1...path.length).each { claim(@shorthand, path.drop(it), package) }
-      end
-
-      def package_for(path)
-        found = path.length.downto(1).filter_map { claimed(path.first(it)) }.first
-        found unless found == AMBIGUOUS
-      end
-
-      private
-
-      def claim(claims, path, package)
-        key = path.join("::")
-        claims[key] = claims.fetch(key, package) == package ? package : AMBIGUOUS
-      end
-
-      def claimed(path)
-        key = path.join("::")
-        @declaring_package[key] || @shorthand[key]
-      end
-    end
+class Hashira::Analysis::ConstantRegistry
+  AMBIGUOUS = Object.new.freeze
+
+  def initialize
+    @origins = {}
+    @shorthand = {}
+  end
+
+  attr_reader :origins
+
+  def register(path, package)
+    return if path.empty?
+    claim(@origins, path, package)
+    (1...path.length).each { claim(@shorthand, path.drop(it), package) }
+  end
+
+  def package(path)
+    found = anchored(path) || enclosing(path)
+    found unless found == AMBIGUOUS
+  end
+
+  def exact(path) = @origins[path.join("::")]
+
+  def packages = (@origins.values.uniq - [AMBIGUOUS])
+
+  private
+
+  def claim(claims, path, package)
+    key = path.join("::")
+    claims[key] = claims.fetch(key, package) == package ? package : AMBIGUOUS
+  end
+
+  def anchored(path)
+    key = path.join("::")
+    @origins[key] || @shorthand[key]
+  end
+
+  def enclosing(path)
+    (path.length - 1).downto(1).filter_map { @origins[path.first(it).join("::")] }.first
   end
 end

data/lib/hashira/analysis/cycle_findings.rb

@@ -1,33 +1,38 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Analysis
-    class CycleFindings < Rule
-      KIND = "cycle"
-
-      def list
-        graph.packages.select { graph.cyclic?(it) }.sort.map { cycle_finding(it) }
-      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
+require_relative "rule"
+
+class Hashira::Analysis::CycleFindings < Hashira::Analysis::Rule
+  KIND = "cycle"
+
+  def list
+    loops.map { entry(it) }
+  end
+
+  private
+
+  def loops
+    cycles = graph.cycles
+    graph.packages.select { cycles.through?(it) }.sort.map { cycles.path(it) }.uniq { it[..-2].sort }
+  end
+
+  def entry(path)
+    package = path.first
+    finding(
+      package:, cycle: path, evidence: evidence(path),
+      message: message(package, path, graph.cycles.weakest(path))
+    )
+  end
+
+  def message(package, path, weak_edge)
+    from, to = weak_edge
+    weight = graph.weight(from, to)
+    "#{package} can reach itself: #{path.join(" -> ")} — any change may ripple back " \
+      "around. The lightest edge on this cycle is #{from} -> #{to} " \
+      "(#{weight} ref#{"s" unless weight == 1})."
+  end
+
+  def evidence(path)
+    path.each_cons(2).flat_map { |from, to| graph.evidence(from, to).to_a.first(2) }
   end
 end

data/lib/hashira/analysis/cycle_search.rb

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

data/lib/hashira/analysis/cycles.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+class Hashira::Analysis::Cycles
+  def initialize(dependencies, graph)
+    @dependencies = dependencies
+    @graph = graph
+  end
+
+  def through?(package) = !!path(package)
+
+  def path(package) = Hashira::Analysis::CycleSearch.new(@dependencies, package).path
+
+  def weakest(trail) = trail.each_cons(2).min_by { |from, to| @graph.weight(from, to) }
+end

data/lib/hashira/analysis/definition.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Hashira
+  module Analysis
+    Definition =
+      Data.define(:node, :path, :folder) do
+        def name = path.first
+
+        def nested? = path.length > 1
+
+        def klass? = node.is_a?(Prism::ClassNode)
+
+        def singular? = klass? && !nested?
+
+        def superclass = node.superclass
+
+        def counted? = klass? || !Hashira::Analysis::Syntax.direct(node).empty?
+      end
+  end
+end

data/lib/hashira/analysis/definitions.rb

@@ -1,27 +1,31 @@
 # frozen_string_literal: true
 
-module Hashira
-  module Analysis
-    class Definitions
-      include Enumerable
+class Hashira::Analysis::Definitions
+  include Enumerable
 
-      def initialize(project, trees)
-        @project = project
-        @trees = trees
-      end
+  def initialize(project, trees)
+    @project = project
+    @trees = trees
+  end
+
+  def each(&)
+    @trees.each { |file, tree| scan(file, tree, &) }
+  end
 
-      def each(&)
-        @trees.each { |file, tree| definitions_in(file, tree, &) }
-      end
+  def packages = @trees.keys.map { @project.package(it) }.uniq
 
-      def packages = @trees.keys.map { @project.package_for(it) }.uniq
+  def roots
+    @roots ||= @trees.each_value.with_object(Set.new) { |tree, set| survey(tree, set) }
+  end
+
+  private
 
-      private
+  def survey(tree, set)
+    Hashira::Analysis::TypeWalk.each(tree) { |_node, full| set << full }
+  end
 
-      def definitions_in(file, tree)
-        package = @project.package_for(file)
-        TypeWalk.each_definition(tree) { |node, full| yield node, full, package }
-      end
-    end
+  def scan(file, tree)
+    package = @project.package(file)
+    Hashira::Analysis::TypeWalk.each(tree, roots: roots) { |node, full| yield(node, full, package) }
   end
 end

data/lib/hashira/analysis/edge.rb

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