moult 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5ad87ca8d76d09c7808a172aa24b42bf8c2031c4c5e05604f1c98e2a1120aacc
-  data.tar.gz: 683a307fa930966927516e37f6b1445b7b0e08c31da996d2c250d8ace63b2e67
+  metadata.gz: 59531e8f248b8da451cabb11f828b81fb25e2c16d6226830eb90321a43ba26f1
+  data.tar.gz: c00350cef7dc2e9618b7fef715cc985e6fc708de655978bd76e0b15296f72c92
 SHA512:
-  metadata.gz: 04d0d5fb568b8135a854d36a89e4b1134a8666007e033465f7e5d56c7566e80dce839a383b333c4dad72cb02054b4b5e87b88954003f8a8d29555e545d5d276f
-  data.tar.gz: 82836397a09f0314f00ae108c339c2a119beb9c0a648323805bbd1a1d9c87b2bbf8191c94e6815837fa1627eb535d9e7c2511df21e8e12ea78ca570ec564dd61
+  metadata.gz: 45b06f38d81c13873caaa309f993ffeea157e63b94b330d3f97cbb1f9a6d0e2b0240e1dce7096207d13bcd238185482011e02ab88cb6ed47558fc1955830b35c
+  data.tar.gz: 0ae644f96a6b055d95c6621e564427e8bb8b031f9a0f61b65c5a4a83dc4fe75b2302304454af6a4ad97b5e515b70b4db3866847e3bbc1c1877dc9dfdd0696845

data/CHANGELOG.md

@@ -12,6 +12,20 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ## [Unreleased]
 
 ### Added
+- `moult cycles` — circular file dependencies over resolved constant
+  references (the dependency signal that survives Zeitwerk autoloading), with
+  a typed contract (`schema/cycles.schema.json`). Each finding carries its
+  member files, the in-cycle evidence edges, and a membership-stable
+  `cycle_group` fingerprint (`"scc:<hash>"`). Report-only; no gate
+  integration.
+- `fan_in`/`fan_out`/`instability` on hotspot findings, from the same
+  constant-reference index (`--no-coupling` to skip). Coupling is context
+  only — the score stays `complexity × churn`. Additive/optional in the
+  schema, so `schema_version` stays 1.
+- Hierarchy-aware dead-code confidence: a new `overrides_unreferenced_ancestor`
+  rule (mild −0.1 brake when the overridden ancestor type is itself
+  unreferenced outside tests) and a new `unreferenced_hierarchy` rule (+0.1
+  when neither the owner type nor any descendant is referenced outside tests).
 - `clone_group` on duplication findings and gate contributions — a
   `"<kind>:<structural-hash>"` join key (kind `identical`|`similar`) shared by
   every occurrence of a clone group, so consumers can link exact twins. Null on
@@ -19,6 +33,9 @@ follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   `schema_version` stays 1.
 
 ### Changed
+- `overrides_ancestor` (−0.4) now fires only when the overridden ancestor type
+  is live or of unknown liveness; a provably unreferenced ancestor downgrades
+  to the mild `overrides_unreferenced_ancestor` brake instead.
 - The gate now emits one duplication contribution per in-diff occurrence
   (previously one per clone group, attributed to its first in-diff
   occurrence), so every site of a clone is visible downstream. Verdicts are

data/README.md

@@ -100,16 +100,23 @@ $ moult hotspots
 
 Hotspots (complexity x churn): 3 files — churn over last 12 months
 
-#  SCORE  COMPLEXITY  CHURN  FILE                    WORST METHOD
-1   95.2        15.9      6  app/services/charge.rb  Charge#call (15.9)
-2   59.6        19.9      3  app/models/user.rb      User#eligible? (15.9)
-3    3.0         3.0      1  lib/util.rb             Util.blank? (3.0)
+#  SCORE  COMPLEXITY  CHURN  IN  OUT  INST  FILE                    WORST METHOD
+1   95.2        15.9      6   4    1  0.20  app/services/charge.rb  Charge#call (15.9)
+2   59.6        19.9      3   7    2  0.22  app/models/user.rb      User#eligible? (15.9)
+3    3.0         3.0      1   0    0  0.00  lib/util.rb             Util.blank? (3.0)
 ```
 
 `app/models/user.rb` is the most *complex* file, but `app/services/charge.rb`
 tops the list because it changes twice as often — complexity alone would have
 missed it.
 
+`IN`/`OUT` are the file's fan-in and fan-out over **resolved constant
+references** (the same index `deadcode` uses — the dependency signal that
+survives Zeitwerk, where `require` lines are absent), and `INST` is the
+instability ratio `fan_out / (fan_in + fan_out)`. Coupling is context, not a
+factor in the score: weighting by instability would bury complex, churned,
+high-fan-in files — exactly the hotspots that matter most.
+
 ### JSON
 
 `--format json` emits the typed contract (see
@@ -136,6 +143,9 @@ moult hotspots --format json
       "score": 95.22,
       "complexity": 15.87,
       "churn": 6,
+      "fan_in": 4,
+      "fan_out": 1,
+      "instability": 0.2,
       "confidence": null,
       "category": null,
       "methods": [
@@ -163,6 +173,7 @@ today — Moult never asserts that code is dead.
 | `--format table\|json` | `table` | Output format. |
 | `--limit N` | `20` | Show the top N hotspots. `0` shows all. |
 | `--since DATE` | `12 months ago` | Churn window start; any value `git log --since` accepts (e.g. `2025-01-01`). |
+| `--[no-]coupling` | on | Compute fan-in/fan-out/instability from a constant-reference index. Off (or on index failure) the columns are `null`/`-`. |
 | `--quiet` | off | Suppress informational notes on stderr. |
 
 Moult is report-only: it exits `0` on success and non-zero only on error. There
@@ -200,12 +211,16 @@ metaprogramming, it never silently hides a candidate.
 Each finding starts from a base score (by kind and visibility) and is adjusted
 by a set of named rules, every one recorded as a `reason`:
 
-- **Raises** confidence: a private method with no caller; a `@deprecated` mark.
+- **Raises** confidence: a private method with no caller; a `@deprecated` mark;
+  a method whose **owner type and all of its descendants are unreferenced**
+  outside tests (no constant path reaches the receiver at all).
 - **Lowers** confidence: a public method (API surface); references only from
   tests; a constructor (`initialize`, invoked implicitly by `.new`); a method
   that **overrides or implements an ancestor's method** (reachable via that
-  interface — polymorphic dispatch); a file that uses
-  `send`/`define_method`/`method_missing`/`const_get`/`eval`.
+  interface — polymorphic dispatch) when the ancestor type is live or of
+  unknown liveness — an ancestor that is itself unreferenced outside tests
+  takes only a mild brake, since the whole hierarchy is likely dead together;
+  a file that uses `send`/`define_method`/`method_missing`/`const_get`/`eval`.
 - **Lowers strongly**: a Rails entrypoint — controller/mailer actions, helpers,
   job `#perform`, `before_action :symbol`-style callbacks, serializers,
   initializers. Rails awareness is on automatically when a Rails app is detected
@@ -329,6 +344,44 @@ hot      method  Charge#call         app/services/charge.rb:2
 cold     method  Report#legacy_to_h  lib/report.rb:42
 ```
 
+## Cycles
+
+```sh
+moult cycles [PATH] [options]
+```
+
+Lists **circular file dependencies**: strongly-connected groups in the file
+graph whose edges are **resolved constant references** — the only dependency
+signal that survives Zeitwerk autoloading, where `require`-based tools see
+nothing. Superclass and mixin clauses flow through the same channel, so
+inheritance edges are included.
+
+```
+$ moult cycles
+
+Circular file dependencies (constant-resolved): 1 cycles
+
+CONF  SIZE  CYCLE             FILES
+0.90     2  scc:64df19a0b7c2  app/models/account.rb -> app/models/user.rb -> app/models/account.rb
+```
+
+`--format json` emits the typed contract (see
+[`schema/cycles.schema.json`](schema/cycles.schema.json)). Each finding carries
+its member `files`, the in-cycle `edges` (each with the referenced constant and
+the reference site's span), and a `cycle_group` fingerprint —
+`"scc:<hash of the sorted member files>"` — that is stable across runs and
+machines, so cycles can be tracked over time. Confidence is `0.9`, not `1.0`:
+a constant reopened in several files fans its edges out to every definition
+file, which can widen a cycle beyond the code that actually participates.
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--format table\|json` | `table` | Output format. |
+| `--quiet` | off | Suppress informational notes on stderr. |
+
+Report-only: exit `0` on success, non-zero only on error. Cycles do not feed
+the gate.
+
 ## How the score works
 
 - **Complexity** — a flog-style weighted ABC score per method: assignments,

data/lib/moult/cli/cycles_command.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult cycles [PATH]` — list circular file dependencies over resolved
+    # constant references. Thin layer: parse options, build the index, drive
+    # the library, hand the {CyclesReport} to a formatter. Report-only: exit 0
+    # on success, non-zero only on error.
+    class CyclesCommand
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = {format: :table, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult cycles [PATH] [options]"
+          o.separator ""
+          o.separator "Options:"
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir, files = Support.discover(root)
+        index = Index.build(root: root_dir, paths: files)
+        edges = index.file_edges
+        note(options, "analysed #{files.size} files; #{edges.size} constant-resolved dependency edges.")
+
+        Cycles.build_report(
+          root: root_dir,
+          edges: edges,
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601,
+          backend_version: rubydex_version,
+          resolved: index.resolved?,
+          diagnostics: index.diagnostics
+        )
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::CyclesJson.render(report)
+        else Formatters::CyclesTable.render(report)
+        end
+      end
+
+      def rubydex_version
+        defined?(Rubydex::VERSION) ? Rubydex::VERSION : nil
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/hotspots_command.rb

@@ -36,7 +36,7 @@ module Moult
       private
 
       def parse(argv)
-        options = {format: :table, limit: DEFAULT_LIMIT, since: Churn::DEFAULT_SINCE, quiet: false}
+        options = {format: :table, limit: DEFAULT_LIMIT, since: Churn::DEFAULT_SINCE, quiet: false, coupling: true}
         @parser = OptionParser.new do |o|
           o.banner = "Usage: moult hotspots [PATH] [options]"
           o.separator ""
@@ -44,6 +44,7 @@ module Moult
           o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
           o.on("--limit N", Integer, "Show top N hotspots (default #{DEFAULT_LIMIT}; 0 for all)") { |v| options[:limit] = v }
           o.on("--since DATE", "Churn window start, any git --since value (default '#{Churn::DEFAULT_SINCE}')") { |v| options[:since] = v }
+          o.on("--[no-]coupling", "Add fan-in/fan-out/instability from a constant-reference index (default on)") { |v| options[:coupling] = v }
           o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
           o.on("-h", "--help", "Show this message") { options[:help] = true }
         end
@@ -74,10 +75,21 @@ module Moult
           git_ref: Git.head_ref(root_dir),
           generated_at: Time.now.utc.iso8601,
           churn_window: window_label(options[:since]),
-          churn_since: explicit_since(options[:since])
+          churn_since: explicit_since(options[:since]),
+          edges: coupling_edges(root_dir, files, options)
         )
       end
 
+      # nil (columns stay null) when coupling is off or the index fails —
+      # a broken index should not take the whole hotspots run down with it.
+      def coupling_edges(root_dir, files, options)
+        return nil unless options[:coupling]
+        Index.build(root: root_dir, paths: files).file_edges
+      rescue Moult::Error => e
+        note(options, "coupling unavailable (#{e.message}); columns left empty.")
+        nil
+      end
+
       def render(report, options)
         limit = (options[:limit] && options[:limit] > 0) ? options[:limit] : nil
         case options[:format]

data/lib/moult/cli.rb

@@ -14,6 +14,7 @@ module Moult
       "deadcode" => ["moult/cli/dead_code_command", :DeadCodeCommand],
       "coverage" => ["moult/cli/coverage_command", :CoverageCommand],
       "duplication" => ["moult/cli/duplication_command", :DuplicationCommand],
+      "cycles" => ["moult/cli/cycles_command", :CyclesCommand],
       "health" => ["moult/cli/health_command", :HealthCommand],
       "boundaries" => ["moult/cli/boundaries_command", :BoundariesCommand],
       "flags" => ["moult/cli/flags_command", :FlagsCommand],
@@ -90,6 +91,7 @@ module Moult
           moult deadcode [PATH] [options]     List confidence-graded dead-code candidates
           moult coverage [PATH] [options]     Map symbols hot/cold/untracked from coverage
           moult duplication [PATH] [options]  List confidence-graded structural-clone groups
+          moult cycles [PATH] [options]       List circular file dependencies (constant-resolved)
           moult health [PATH] [options]       Aggregate the analyses into a composite health score
           moult boundaries [PATH] [options]   List recorded architecture-boundary violations (packwerk)
           moult flags [PATH] [options]        Catalogue OpenFeature feature-flag references (usage)

data/lib/moult/confidence/rules.rb

@@ -65,13 +65,36 @@ module Moult
         # through that ancestor's interface (polymorphic dispatch) even with no
         # by-name call site — the same signal a typed tool gets free from its
         # inheritance graph. Covers framework hooks (visitor #visit_*, job
-        # #perform) when the ancestor's source is indexed.
+        # #perform) when the ancestor's source is indexed. Fires when the
+        # ancestor type is live or of unknown liveness (Object, gems:
+        # conservative); a provably unreferenced ancestor downgrades to the
+        # weaker rule below instead.
         Rule.new(
           name: :overrides_ancestor,
-          applies: ->(c) { c.override_of },
+          applies: ->(c) { c.override_of && c.override_live != false },
           delta: -0.4,
           detail: ->(c) { "overrides #{c.override_of} (reachable via that interface)" }
         ),
+        # The overridden ancestor type itself has no production reference: the
+        # polymorphic path exists syntactically, but nothing names the type, so
+        # the hierarchy is likely dead together. A mild brake, not the full
+        # -0.4 — the reachability is mostly moot.
+        Rule.new(
+          name: :overrides_unreferenced_ancestor,
+          applies: ->(c) { c.override_of && c.override_live == false },
+          delta: -0.1,
+          detail: ->(c) { "overrides #{c.override_of}, but that ancestor type is itself unreferenced outside tests" }
+        ),
+        # Neither the owner type nor any of its descendants is referenced in
+        # production: no constant path reaches the method's receiver at all.
+        # Modest raise — dynamic-dispatch and Rails rescue rules must still be
+        # able to counteract it.
+        Rule.new(
+          name: :unreferenced_hierarchy,
+          applies: ->(c) { c.hierarchy_referenced == false },
+          delta: 0.1,
+          detail: "no reference to the owner type or any of its descendants outside tests"
+        ),
         Rule.new(
           name: :private_unused,
           applies: ->(c) { c.kind == :method && c.visibility == :private && c.reference_count.to_i.zero? },

data/lib/moult/confidence.rb

@@ -39,7 +39,9 @@ module Moult
       :override_of,        # String, nil: ancestor whose method this overrides
       :deprecated,         # Boolean
       :index_resolved,
-      :runtime             # Symbol, nil: :hot/:cold/:untracked from coverage (Phase 3)
+      :runtime,            # Symbol, nil: :hot/:cold/:untracked from coverage (Phase 3)
+      :override_live,      # Boolean, nil: the overridden ancestor type has a production reference; nil = ancestor not indexed (unknown)
+      :hierarchy_referenced # Boolean, nil: the owner type or a descendant has a production reference; nil = owner not indexed (unknown)
     )
 
     # One auditable contribution to a finding's confidence.

data/lib/moult/cycles.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Moult
+  # File-level circular dependencies over the {Index#file_edges} graph. Every
+  # edge is a *resolved* constant reference — the only dependency signal that
+  # survives Zeitwerk autoloading, where `require` lines are absent — so each
+  # cycle is backed by concrete reference sites, never name matching.
+  module Cycles
+    # High because every edge is a resolved constant reference, but not 1.0: a
+    # constant reopened in several files fans its edges out to every definition
+    # file, which can widen a cycle beyond the code that actually participates.
+    CONFIDENCE = 0.9
+
+    CATEGORY = "cycle"
+
+    module_function
+
+    # @param root [String] absolute analysis root
+    # @param edges [Array<Index::Edge>] file dependency edges
+    # @return [CyclesReport] findings ranked largest cycle first
+    def build_report(root:, edges:, git_ref: nil, generated_at: nil,
+      backend_version: nil, resolved: true, diagnostics: [])
+      components = strongly_connected(adjacency(edges))
+      findings = components.select { |c| c.size >= 2 }.map { |c| finding_for(c, edges) }
+      findings.sort_by! { |f| [-f.size, f.files.first] }
+      CyclesReport.new(
+        root: root, findings: findings, git_ref: git_ref, generated_at: generated_at,
+        backend: "rubydex", backend_version: backend_version,
+        resolved: resolved, diagnostics: diagnostics
+      )
+    end
+
+    # Sorted node => sorted children over every file named by an edge, so the
+    # SCC walk (and therefore the report) is deterministic regardless of the
+    # order edges arrive in.
+    def adjacency(edges)
+      adj = {}
+      edges.each do |edge|
+        (adj[edge.src] ||= []) << edge.dst
+        adj[edge.dst] ||= []
+      end
+      adj.keys.sort.to_h { |node| [node, adj[node].uniq.sort] }
+    end
+
+    # Tarjan's strongly-connected components with an explicit work stack.
+    # ponytail: hand-rolled because stdlib TSort's SCC walk is recursive and
+    # SystemStackErrors on cycles a few thousand files deep (measured at ~5k);
+    # swap back to TSort if it ever gains an iterative walker.
+    def strongly_connected(adj)
+      index = {}
+      lowlink = {}
+      on_stack = {}
+      stack = []
+      components = []
+      counter = 0
+
+      adj.each_key do |start|
+        next if index.key?(start)
+        work = [[start, 0]]
+        until work.empty?
+          frame = work.last
+          node = frame[0]
+          if frame[1].zero? # first visit
+            index[node] = lowlink[node] = counter
+            counter += 1
+            stack << node
+            on_stack[node] = true
+          end
+
+          children = adj[node]
+          pushed = false
+          while frame[1] < children.size
+            child = children[frame[1]]
+            frame[1] += 1
+            if !index.key?(child)
+              work << [child, 0]
+              pushed = true
+              break
+            elsif on_stack[child]
+              lowlink[node] = [lowlink[node], index[child]].min
+            end
+          end
+          next if pushed
+
+          work.pop
+          if lowlink[node] == index[node]
+            component = []
+            loop do
+              member = stack.pop
+              on_stack.delete(member)
+              component << member
+              break if member == node
+            end
+            components << component
+          end
+          parent = work.last&.first
+          lowlink[parent] = [lowlink[parent], lowlink[node]].min if parent
+        end
+      end
+      components
+    end
+
+    def finding_for(component, edges)
+      files = component.sort
+      member = component.to_h { |f| [f, true] }
+      evidence = edges.select { |e| member[e.src] && member[e.dst] && e.src != e.dst }
+        .sort_by { |e| [e.src, e.dst] }
+      CyclesReport::Finding.new(
+        cycle_group: fingerprint(files),
+        confidence: CONFIDENCE,
+        category: CATEGORY,
+        size: files.size,
+        files: files,
+        reasons: [Confidence::Reason.new(
+          rule: :resolved_constant_edges,
+          delta: CONFIDENCE,
+          detail: "every edge is a resolved constant reference; reopened constants can widen a cycle"
+        )],
+        edges: evidence
+      )
+    end
+
+    # Membership-stable across runs and machines (unlike a detector-backend
+    # hash): the same set of files is the same cycle, however its edges shift.
+    def fingerprint(files)
+      "scc:#{Digest::SHA256.hexdigest(files.join("\n"))[0, 12]}"
+    end
+  end
+end

data/lib/moult/cycles_report.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult cycles` (schema/cycles.schema.json),
+  # sibling to {DuplicationReport} and {DeadCodeReport}. Each {Finding} is one
+  # strongly-connected component of the file dependency graph, carrying the
+  # resolved constant-reference edges as its evidence.
+  class CyclesReport
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    # One circular file-dependency group. +cycle_group+ ("scc:<hash of the
+    # sorted member files>") is the group's join key — membership-stable
+    # across runs and machines, unlike a detector-backend hash. +edges+ are
+    # the in-cycle dependencies, each with a representative reference site.
+    Finding = Struct.new(:cycle_group, :confidence, :category, :size, :files, :reasons, :edges) do
+      def to_h
+        {
+          cycle_group: cycle_group,
+          category: category,
+          confidence: confidence,
+          size: size,
+          files: files,
+          reasons: reasons.map(&:to_h),
+          edges: edges.map { |e| {src: e.src, dst: e.dst, constant: e.constant, span: e.span.to_h} }
+        }
+      end
+    end
+
+    attr_reader :root, :findings, :git_ref, :generated_at,
+      :backend, :backend_version, :resolved, :diagnostics
+
+    # @param root [String] absolute analysis root
+    # @param findings [Array<Finding>] ranked, largest cycle first
+    # @param backend [String] index backend name (e.g. "rubydex")
+    # @param backend_version [String, nil] backend gem version
+    def initialize(root:, findings:, git_ref: nil, generated_at: nil,
+      backend: "rubydex", backend_version: nil, resolved: true, diagnostics: [])
+      @root = root
+      @findings = findings
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @backend = backend
+      @backend_version = backend_version
+      @resolved = resolved
+      @diagnostics = diagnostics
+    end
+
+    # @return [Hash] aggregate counts across all cycles
+    def summary
+      {
+        cycles: findings.size,
+        files: findings.sum { |f| f.files.size },
+        largest: findings.map(&:size).max || 0
+      }
+    end
+
+    def to_h
+      {
+        schema_version: SCHEMA_VERSION,
+        tool: {name: "moult", version: Moult::VERSION},
+        analysis: {
+          root: root,
+          git_ref: git_ref,
+          generated_at: generated_at,
+          index: {
+            backend: backend,
+            backend_version: backend_version,
+            resolved: resolved,
+            diagnostics: diagnostics
+          }
+        },
+        summary: summary,
+        findings: findings.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/moult/dead_code.rb

@@ -40,10 +40,12 @@ module Moult
     def build_report(root:, files:, index:, rails:, min_confidence: 0.0,
       git_ref: nil, generated_at: nil, backend_version: nil, coverage: nil)
       dynamic_files = dynamic_dispatch_files(files, root)
+      constant_live = constant_liveness(index)
 
       findings = index.definitions.filter_map do |definition|
         next unless candidate?(definition)
-        Confidence.score(context_for(definition, index: index, rails: rails, dynamic_files: dynamic_files, coverage: coverage))
+        Confidence.score(context_for(definition, index: index, rails: rails, dynamic_files: dynamic_files,
+          coverage: coverage, constant_live: constant_live))
       end
 
       findings.select! { |f| f.confidence >= min_confidence }
@@ -68,7 +70,7 @@ module Moult
       non_test_reference_paths(definition).empty?
     end
 
-    def context_for(definition, index:, rails:, dynamic_files:, coverage: nil)
+    def context_for(definition, index:, rails:, dynamic_files:, coverage: nil, constant_live: {})
       Confidence::Context.new(
         symbol_id: definition.symbol_id,
         kind: definition.kind,
@@ -83,10 +85,34 @@ module Moult
         override_of: definition.override_of,
         deprecated: false,
         index_resolved: index.resolved?,
-        runtime: runtime_for(definition, coverage)
+        runtime: runtime_for(definition, coverage),
+        override_live: definition.override_of && constant_live[definition.override_of],
+        hierarchy_referenced: hierarchy_referenced?(definition)
       )
     end
 
+    # Whether the owner type or any descendant is referenced outside tests.
+    # nil (unknown) propagates from the index; test filtering stays here,
+    # matching the reference_paths convention — the Index never learns what a
+    # test path is.
+    def hierarchy_referenced?(definition)
+      paths = definition.owner_hierarchy_reference_paths
+      return nil if paths.nil?
+      Array(paths).reject { |path| path.to_s.match?(TEST_PATH) }.any?
+    end
+
+    # FQ constant name => whether it has a production (non-test) reference.
+    # The liveness join for override_live: an override's ancestor *method*
+    # shares the override's name-keyed references, so the honest signal is the
+    # ancestor *type*'s constant references. Reopened constants OR together;
+    # a name absent from this map (Object, gems) stays nil — unknown.
+    def constant_liveness(index)
+      index.definitions.each_with_object({}) do |d, acc|
+        next unless d.kind == :constant
+        acc[d.name] = acc[d.name] || non_test_reference_paths(d).any?
+      end
+    end
+
     # The runtime classification for this definition, joined on the same path +
     # span that make up its symbol_id. nil when no coverage was supplied.
     def runtime_for(definition, coverage)

data/lib/moult/formatters/cycles_json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # Emits the typed cycles JSON contract (schema/cycles.schema.json). Renders
+    # straight from {CyclesReport#to_h} so the serialized shape cannot drift
+    # from the result model.
+    module CyclesJson
+      module_function
+
+      # @param report [CyclesReport]
+      # @return [String] pretty-printed JSON
+      def render(report)
+        JSON.pretty_generate(report.to_h)
+      end
+    end
+  end
+end

data/lib/moult/formatters/cycles_table.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable table of circular file dependencies. Renders from the same
+    # {CyclesReport} as the JSON formatter so the two cannot disagree. Sorting
+    # already happened in {Cycles}; this layer owns column formatting only.
+    module CyclesTable
+      MAX_FILES = 3
+      RIGHT_ALIGNED = [0, 1].freeze # CONF, SIZE
+
+      module_function
+
+      # @param report [CyclesReport]
+      # @return [String]
+      def render(report)
+        findings = report.findings
+        return "No cycles found." if findings.empty?
+
+        headers = %w[CONF SIZE CYCLE FILES]
+        rows = findings.map { |f| row(f) }
+        [heading(findings.size), "", TextTable.render(headers, rows, right_aligned: RIGHT_ALIGNED)].join("\n")
+      end
+
+      def heading(count)
+        "Circular file dependencies (constant-resolved): #{count} cycles"
+      end
+
+      def row(finding)
+        [
+          format("%.2f", finding.confidence),
+          finding.size.to_s,
+          finding.cycle_group,
+          chain(finding.files)
+        ]
+      end
+
+      # "a.rb -> b.rb -> a.rb" for small cycles; "a.rb -> b.rb -> c.rb (+2 more)"
+      # once the membership no longer fits.
+      def chain(files)
+        shown = files.first(MAX_FILES)
+        extra = files.size - shown.size
+        return "#{shown.join(" -> ")} (+#{extra} more)" if extra.positive?
+        "#{shown.join(" -> ")} -> #{files.first}"
+      end
+    end
+  end
+end

data/lib/moult/formatters/table.rb

@@ -6,9 +6,9 @@ module Moult
     # formatter, so the two cannot disagree. Sorting already happened in
     # {Scoring}; this layer owns limiting and column formatting only.
     module Table
-      HEADERS = ["#", "SCORE", "COMPLEXITY", "CHURN", "FILE", "WORST METHOD"].freeze
+      HEADERS = ["#", "SCORE", "COMPLEXITY", "CHURN", "IN", "OUT", "INST", "FILE", "WORST METHOD"].freeze
       # Right-align the numeric columns; left-align file and method.
-      RIGHT_ALIGNED = [0, 1, 2, 3].freeze
+      RIGHT_ALIGNED = [0, 1, 2, 3, 4, 5, 6].freeze
       GUTTER = "  "
 
       module_function
@@ -40,6 +40,9 @@ module Moult
           num(hotspot.score),
           num(hotspot.complexity),
           hotspot.churn.to_s,
+          hotspot.fan_in ? hotspot.fan_in.to_s : "-",
+          hotspot.fan_out ? hotspot.fan_out.to_s : "-",
+          hotspot.instability ? format("%.2f", hotspot.instability) : "-",
           hotspot.path,
           worst_cell
         ]

data/lib/moult/index.rb

@@ -30,12 +30,24 @@ module Moult
     # @!attribute reference_paths [Array<String>] root-relative paths that use it
     # @!attribute override_of [String, nil] FQ name of the ancestor whose method
     #   this overrides/implements (reachable via that interface), else nil
+    # @!attribute owner_hierarchy_reference_paths [Array<String>, nil] for
+    #   methods: root-relative paths referencing the owner type or any
+    #   descendant, excluding the hierarchy's own definition files. nil when
+    #   the owner is unknown or defined outside the workspace (fact
+    #   unavailable), and always nil for constants (their own reference_paths
+    #   already carry the signal)
     Definition = Struct.new(
       :symbol_id, :kind, :name, :unqualified_name, :owner,
       :visibility, :singleton, :span, :path,
-      :reference_count, :reference_paths, :override_of
+      :reference_count, :reference_paths, :override_of,
+      :owner_hierarchy_reference_paths
     )
 
+    # One resolved constant-reference dependency between two workspace files.
+    # +constant+/+span+ identify a representative reference site (the earliest
+    # in +src+), kept as evidence rather than every duplicate site.
+    Edge = Struct.new(:src, :dst, :constant, :span)
+
     BUILTIN_SCHEME = "file:"
 
     class << self
@@ -88,6 +100,33 @@ module Moult
       []
     end
 
+    # @return [Array<Index::Edge>] unique src->dst file dependencies from
+    #   resolved constant references (superclass and mixin clauses flow through
+    #   the same list, so inheritance edges are included). A constant reopened
+    #   in N files yields an edge to every in-workspace definition file;
+    #   self-edges and qualifier segments are dropped. Sorted by [src, dst] so
+    #   output is byte-stable regardless of rubydex iteration order.
+    def file_edges
+      @file_edges ||= begin
+        edges = {}
+        resolved = @graph.constant_references.select { |r| r.is_a?(Rubydex::ResolvedConstantReference) }
+        qualifiers = qualifier_references(resolved)
+        resolved.each do |ref|
+          next if qualifiers.include?(ref)
+          src = workspace_relative(ref.location)
+          next unless src
+          span = span_from(ref.location)
+          in_workspace_definitions(ref.declaration).each do |_defn, _span, dst|
+            next if dst == src
+            existing = edges[[src, dst]]
+            next if existing && existing.span.start_line <= span.start_line
+            edges[[src, dst]] = Edge.new(src: src, dst: dst, constant: ref.declaration.name, span: span)
+          end
+        end
+        edges.values.sort_by { |e| [e.src, e.dst] }
+      end
+    end
+
     private
 
     def method_definitions
@@ -96,6 +135,7 @@ module Moult
         unqualified = strip_signature(decl.unqualified_name)
         sites = method_call_sites[unqualified]
         override = override_source(decl)
+        hierarchy_refs = hierarchy_reference_paths(decl.owner)
         in_workspace_definitions(decl).map do |defn, span, rel|
           Definition.new(
             symbol_id: SymbolId.for(path: rel, start_line: span.start_line, fqname: name),
@@ -109,7 +149,8 @@ module Moult
             path: rel,
             reference_count: sites.size,
             reference_paths: sites.compact.uniq,
-            override_of: override
+            override_of: override,
+            owner_hierarchy_reference_paths: hierarchy_refs
           )
         end
       end
@@ -160,6 +201,26 @@ module Moult
       end
     end
 
+    # The qualifier segments of constant paths. In `Moult::Error`, rubydex
+    # records a resolved reference for the `Moult` token as well as one for
+    # `Error` — but the file dependency is on where *Error* is defined. A root
+    # namespace reopened in every file (`module Moult` in each) would otherwise
+    # fan edges out to the entire codebase, drowning the graph. A reference is
+    # a qualifier when a same-line reference to a deeper constant in its own
+    # namespace starts exactly two columns (the `::`) after it ends.
+    def qualifier_references(resolved)
+      by_line = resolved.group_by { |r| [r.location&.uri, r.location&.start_line] }
+      resolved.each_with_object(Set.new) do |ref, quals|
+        loc = ref.location
+        next unless loc
+        deeper = "#{ref.declaration.name}::"
+        quals << ref if by_line[[loc.uri, loc.start_line]].any? do |other|
+          other.declaration.name.start_with?(deeper) &&
+            other.location.start_column == loc.end_column + 2
+        end
+      end
+    end
+
     def in_workspace?(location)
       return false unless location
       uri = location.uri
@@ -210,6 +271,33 @@ module Moult
       nil
     end
 
+    # Production-reachability of a method's receiver type: the root-relative
+    # paths of constant references to the owner namespace or any descendant,
+    # minus the hierarchy's own definition files — a subclass's `< Base`
+    # clause is itself a reference to Base and would otherwise make the result
+    # never empty. nil when the owner is unknown or defined outside the
+    # workspace (Object, gems): the fact is unavailable, not "unreferenced".
+    # Cached per owner so one descendants walk serves all of its methods.
+    def hierarchy_reference_paths(owner)
+      return nil unless owner
+      @hierarchy_refs ||= {}
+      return @hierarchy_refs[owner.name] if @hierarchy_refs.key?(owner.name)
+      @hierarchy_refs[owner.name] = begin
+        # def self.x lives on the singleton class; judge the class itself.
+        target = owner.is_a?(Rubydex::SingletonClass) ? owner.attached_class : owner
+        if target.is_a?(Rubydex::Namespace)
+          namespaces = ([target] + target.descendants.to_a).uniq(&:name)
+          own_files = namespaces.flat_map { |ns| in_workspace_definitions(ns).map { |_defn, _span, rel| rel } }.uniq
+          unless own_files.empty?
+            namespaces.flat_map { |ns| ns.references.map { |ref| workspace_relative(ref.location) } }
+              .compact.uniq - own_files
+          end
+        end
+      rescue
+        nil
+      end
+    end
+
     def visibility_of(decl)
       vis = decl.visibility if decl.respond_to?(:visibility)
       %i[public private protected].include?(vis) ? vis : :public

data/lib/moult/report.rb

@@ -47,19 +47,29 @@ module Moult
 
     # One ranked file.
     class Hotspot
-      attr_reader :path, :score, :complexity, :churn, :methods, :confidence, :category
+      attr_reader :path, :score, :complexity, :churn, :methods,
+        :fan_in, :fan_out, :instability, :confidence, :category
 
       # @param path [String] path relative to the analysis root
       # @param score [Float] complexity x churn
       # @param complexity [Float] aggregate ABC for the file
       # @param churn [Integer] commits touching the file in the window
       # @param methods [Array<Method>] worst methods, highest ABC first
-      def initialize(path:, score:, complexity:, churn:, methods:, confidence: nil, category: nil)
+      # @param fan_in [Integer, nil] files depending on this file (resolved
+      #   constant references); nil when no index was built
+      # @param fan_out [Integer, nil] files this file depends on; nil likewise
+      # @param instability [Float, nil] fan_out / (fan_in + fan_out); 0 when
+      #   isolated, nil when no index was built
+      def initialize(path:, score:, complexity:, churn:, methods:,
+        fan_in: nil, fan_out: nil, instability: nil, confidence: nil, category: nil)
         @path = path
         @score = score
         @complexity = complexity
         @churn = churn
         @methods = methods
+        @fan_in = fan_in
+        @fan_out = fan_out
+        @instability = instability
         @confidence = confidence
         @category = category
       end
@@ -75,6 +85,9 @@ module Moult
           score: score,
           complexity: complexity,
           churn: churn,
+          fan_in: fan_in,
+          fan_out: fan_out,
+          instability: instability,
           confidence: confidence,
           category: category,
           methods: methods.map(&:to_h)

data/lib/moult/scoring.rb

@@ -23,11 +23,14 @@ module Moult
     # @param files [Array<String>] absolute paths of Ruby files to analyse
     # @param churn [Hash{String=>Integer}] path (relative to root) => commit count
     # @param worst_methods [Integer] how many worst methods to keep per file
+    # @param edges [Array<#src,#dst>, nil] unique file dependency pairs (e.g.
+    #   {Index#file_edges}); nil leaves the coupling columns null
     # @return [Report]
     def build_report(root:, files:, churn:, worst_methods: DEFAULT_WORST_METHODS,
-      git_ref: nil, generated_at: nil, churn_window: nil, churn_since: nil)
+      git_ref: nil, generated_at: nil, churn_window: nil, churn_since: nil, edges: nil)
+      coupling = coupling_degrees(edges)
       hotspots = files.filter_map do |abs|
-        hotspot_for(abs, root: root, churn: churn, worst_methods: worst_methods)
+        hotspot_for(abs, root: root, churn: churn, worst_methods: worst_methods, coupling: coupling)
       end
       hotspots.sort_by! { |h| [-h.score, -h.complexity, h.path] }
 
@@ -42,7 +45,7 @@ module Moult
     end
 
     # @return [Report::Hotspot, nil] nil when the file has no scoring methods
-    def hotspot_for(abs, root:, churn:, worst_methods:)
+    def hotspot_for(abs, root:, churn:, worst_methods:, coupling: nil)
       rel = relative_path(abs, root)
       methods = Parser.parse_file(abs).map { |m| build_method(m, rel) }
       complexity = methods.sum(0.0, &:abc)
@@ -56,16 +59,43 @@ module Moult
         score: combine(complexity, churn_count).round(2),
         complexity: complexity.round(2),
         churn: churn_count,
-        methods: kept
+        methods: kept,
+        **coupling_fields(rel, coupling)
       )
     end
 
-    # The v0.1 scoring rule. Swap-point for future normalisation.
+    # The v0.1 scoring rule. Swap-point for future normalisation. Coupling is
+    # deliberately not a factor: weighting by instability would bury complex,
+    # churned, high-fan-in files — exactly the hotspots that matter most.
     # @return [Numeric]
     def combine(complexity, churn)
       complexity * churn
     end
 
+    # In/out degree per file over the unique dependency pairs. nil when no
+    # edges were supplied (coupling unknown).
+    def coupling_degrees(edges)
+      return nil unless edges
+      {
+        out: edges.group_by(&:src).transform_values(&:size),
+        in: edges.group_by(&:dst).transform_values(&:size)
+      }
+    end
+
+    # A file absent from the edge set is measured-as-isolated (0/0), not
+    # unknown: the index saw it and found no resolved dependencies.
+    def coupling_fields(rel, coupling)
+      return {fan_in: nil, fan_out: nil, instability: nil} unless coupling
+      fan_in = coupling[:in][rel] || 0
+      fan_out = coupling[:out][rel] || 0
+      total = fan_in + fan_out
+      {
+        fan_in: fan_in,
+        fan_out: fan_out,
+        instability: total.zero? ? 0.0 : (fan_out.to_f / total).round(2)
+      }
+    end
+
     def build_method(method_def, rel)
       Report::Method.new(
         symbol_id: SymbolId.for(path: rel, start_line: method_def.span.start_line, fqname: method_def.name),

data/lib/moult/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moult
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/moult.rb

@@ -38,6 +38,10 @@ module Moult
   autoload :Duplication, "moult/duplication"
   autoload :DuplicationReport, "moult/duplication_report"
 
+  # Static slice: circular file dependencies over resolved constant references.
+  autoload :Cycles, "moult/cycles"
+  autoload :CyclesReport, "moult/cycles_report"
+
   # Health slice: a composite health score aggregating the other analyses.
   autoload :Health, "moult/health"
   autoload :HealthReport, "moult/health_report"
@@ -69,6 +73,8 @@ module Moult
     autoload :CoverageJson, "moult/formatters/coverage_json"
     autoload :DuplicationTable, "moult/formatters/duplication_table"
     autoload :DuplicationJson, "moult/formatters/duplication_json"
+    autoload :CyclesTable, "moult/formatters/cycles_table"
+    autoload :CyclesJson, "moult/formatters/cycles_json"
     autoload :HealthTable, "moult/formatters/health_table"
     autoload :HealthJson, "moult/formatters/health_json"
     autoload :BoundariesTable, "moult/formatters/boundaries_table"

data/schema/cycles.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/cycles.schema.json",
+  "title": "Moult cycles report",
+  "description": "Typed output contract for `moult cycles`. Each finding is one strongly-connected component of the file dependency graph built from resolved constant references, carrying its evidence edges; nothing here asserts that a cycle is certainly harmful.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "summary", "findings"],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "description": "Bumped only on a breaking change to this shape.",
+      "type": "integer",
+      "const": 1
+    },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {"type": "string"},
+        "version": {"type": "string"}
+      }
+    },
+    "analysis": {
+      "type": "object",
+      "required": ["root", "git_ref", "generated_at", "index"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "index": {
+          "type": "object",
+          "required": ["backend", "backend_version", "resolved", "diagnostics"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"type": "string"},
+            "backend_version": {"type": ["string", "null"]},
+            "resolved": {"type": "boolean"},
+            "diagnostics": {"type": "array", "items": {"type": "string"}}
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["cycles", "files", "largest"],
+      "additionalProperties": false,
+      "properties": {
+        "cycles": {"description": "Number of circular dependency groups.", "type": "integer", "minimum": 0},
+        "files": {"description": "Total files across all cycles.", "type": "integer", "minimum": 0},
+        "largest": {"description": "File count of the largest cycle; 0 when none.", "type": "integer", "minimum": 0}
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable contribution to a finding's confidence.",
+      "type": "object",
+      "required": ["rule", "delta", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "delta": {"description": "Signed adjustment this rule applied.", "type": "number"},
+        "detail": {"type": "string"}
+      }
+    },
+    "edge": {
+      "description": "One in-cycle file dependency, evidenced by a representative resolved constant-reference site in the source file.",
+      "type": "object",
+      "required": ["src", "dst", "constant", "span"],
+      "additionalProperties": false,
+      "properties": {
+        "src": {"description": "Root-relative path of the referencing file.", "type": "string"},
+        "dst": {"description": "Root-relative path of the file defining the referenced constant.", "type": "string"},
+        "constant": {"description": "Fully-qualified name of the referenced constant.", "type": "string"},
+        "span": {"$ref": "common.schema.json#/$defs/span"}
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["cycle_group", "category", "confidence", "size", "files", "reasons", "edges"],
+      "additionalProperties": false,
+      "properties": {
+        "cycle_group": {
+          "description": "Cycle join key, \"scc:<hash of the sorted member files>\". Membership-stable across runs and machines: the same set of files is the same cycle, however its edges shift.",
+          "type": "string",
+          "pattern": "^scc:"
+        },
+        "category": {
+          "description": "Always \"cycle\" in this contract.",
+          "type": "string"
+        },
+        "confidence": {
+          "description": "Likelihood this is a genuine dependency cycle, in [0, 1]. High (edges are resolved constant references) but never 1: reopened constants can widen a cycle.",
+          "$ref": "common.schema.json#/$defs/unit_interval"
+        },
+        "size": {
+          "description": "Number of files in the cycle.",
+          "type": "integer",
+          "minimum": 2
+        },
+        "files": {
+          "description": "Sorted root-relative paths of the cycle's members.",
+          "type": "array",
+          "minItems": 2,
+          "items": {"type": "string"}
+        },
+        "reasons": {
+          "description": "The factors behind the confidence, in application order.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        },
+        "edges": {
+          "description": "The in-cycle dependencies; a cycle has at least two.",
+          "type": "array",
+          "minItems": 2,
+          "items": {"$ref": "#/$defs/edge"}
+        }
+      }
+    }
+  }
+}

data/schema/hotspots.schema.json

@@ -93,6 +93,23 @@
           "type": "integer",
           "minimum": 0
         },
+        "fan_in": {
+          "description": "Files depending on this file via resolved constant references. Null when no index was built (--no-coupling or index failure).",
+          "type": ["integer", "null"],
+          "minimum": 0
+        },
+        "fan_out": {
+          "description": "Files this file depends on via resolved constant references. Null when no index was built.",
+          "type": ["integer", "null"],
+          "minimum": 0
+        },
+        "instability": {
+          "description": "fan_out / (fan_in + fan_out); 0 when the file is isolated. Null when no index was built.",
+          "oneOf": [
+            {"type": "null"},
+            {"$ref": "common.schema.json#/$defs/unit_interval"}
+          ]
+        },
         "methods": {
           "description": "Worst methods in the file, highest ABC first.",
           "type": "array",

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moult
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Brandyn Britton
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-05 00:00:00.000000000 Z
+date: 2026-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -79,6 +79,7 @@ files:
 - lib/moult/cli.rb
 - lib/moult/cli/boundaries_command.rb
 - lib/moult/cli/coverage_command.rb
+- lib/moult/cli/cycles_command.rb
 - lib/moult/cli/dead_code_command.rb
 - lib/moult/cli/duplication_command.rb
 - lib/moult/cli/flags_command.rb
@@ -92,6 +93,8 @@ files:
 - lib/moult/coverage.rb
 - lib/moult/coverage/resolver.rb
 - lib/moult/coverage_report.rb
+- lib/moult/cycles.rb
+- lib/moult/cycles_report.rb
 - lib/moult/dead_code.rb
 - lib/moult/dead_code_report.rb
 - lib/moult/diff.rb
@@ -109,6 +112,8 @@ files:
 - lib/moult/formatters/boundaries_table.rb
 - lib/moult/formatters/coverage_json.rb
 - lib/moult/formatters/coverage_table.rb
+- lib/moult/formatters/cycles_json.rb
+- lib/moult/formatters/cycles_table.rb
 - lib/moult/formatters/dead_code_json.rb
 - lib/moult/formatters/dead_code_table.rb
 - lib/moult/formatters/duplication_json.rb
@@ -146,6 +151,7 @@ files:
 - schema/boundaries.schema.json
 - schema/common.schema.json
 - schema/coverage.schema.json
+- schema/cycles.schema.json
 - schema/deadcode.schema.json
 - schema/duplication.schema.json
 - schema/flags.schema.json