moult 0.1.0

data/lib/moult/abc.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Moult
+  # Flog-style weighted ABC complexity for a single method.
+  #
+  # This is *not* the bare ABC metric (sqrt(A^2 + B^2 + C^2)). Following flog,
+  # the score is a weighted *sum* of three buckets, with metaprogramming calls
+  # penalised and a compounding depth penalty for nesting:
+  #
+  #   * A - Assignments: any write node (`=`, op-assign, `||=`, multi-assign,
+  #     `obj.x =`, `arr[i] =`). Weight {ASSIGNMENT}. Counted once per write node.
+  #   * B - Branches: every message send ({Prism::CallNode}, including operators
+  #     like `+` and `==` and index `[]`), plus `yield` and `super`. Weight
+  #     {BRANCH}, except metaprogramming calls in {MAGIC_CALLS}, which weigh more.
+  #   * C - Conditions: decision nodes - if/unless/while/until/for, case + each
+  #     when/in, rescue, and `&&`/`||`. Weight {CONDITION}.
+  #
+  # Depth penalty: contributions nested inside a control structure or block are
+  # multiplied by {DEPTH_FACTOR} per level, compounding. A call directly in the
+  # method body weighs 1.0; the same call one `if` deep weighs 1.1; two deep,
+  # 1.21; and so on.
+  #
+  # flog is the reference for the *shape* of this metric; the exact weights below
+  # are the ones Moult adopts and are pinned by hand-counted fixtures. Treat any
+  # drift from those fixtures as a metric bug.
+  module ABC
+    ASSIGNMENT = 1.0
+    BRANCH = 1.0
+    CONDITION = 1.0
+
+    # Each level of control-flow / block nesting compounds contributions by 10%.
+    DEPTH_FACTOR = 1.1
+
+    # Metaprogramming and dynamic-dispatch calls weigh more than an ordinary
+    # send, mirroring flog's penalties for hard-to-follow Ruby.
+    MAGIC_CALLS = {
+      eval: 5.0,
+      instance_eval: 5.0,
+      class_eval: 5.0,
+      module_eval: 5.0,
+      class_exec: 5.0,
+      instance_exec: 5.0,
+      define_method: 4.0,
+      define_singleton_method: 4.0,
+      method_missing: 4.0,
+      alias_method: 2.0,
+      send: 3.0,
+      __send__: 3.0,
+      public_send: 3.0
+    }.freeze
+
+    BRANCH_NODES = [
+      Prism::CallNode,
+      Prism::YieldNode,
+      Prism::SuperNode,
+      Prism::ForwardingSuperNode
+    ].freeze
+
+    CONDITION_NODES = [
+      Prism::IfNode,
+      Prism::UnlessNode,
+      Prism::WhileNode,
+      Prism::UntilNode,
+      Prism::ForNode,
+      Prism::CaseNode,
+      Prism::CaseMatchNode,
+      Prism::WhenNode,
+      Prism::InNode,
+      Prism::RescueNode,
+      Prism::AndNode,
+      Prism::OrNode
+    ].freeze
+
+    # Nodes whose children sit one nesting level deeper. Containers only - the
+    # when/in/&&/|| conditions don't bump again on top of their container.
+    NESTING_NODES = [
+      Prism::IfNode,
+      Prism::UnlessNode,
+      Prism::WhileNode,
+      Prism::UntilNode,
+      Prism::ForNode,
+      Prism::CaseNode,
+      Prism::CaseMatchNode,
+      Prism::RescueNode,
+      Prism::BlockNode,
+      Prism::LambdaNode
+    ].freeze
+
+    module_function
+
+    # @param def_node [Prism::DefNode] a method definition
+    # @return [Float] the method's weighted ABC score, rounded to 2 decimals
+    def score(def_node)
+      total = walk(def_node, 1.0, root: true)
+      total.round(2)
+    end
+
+    # Recursively accumulate weighted contributions. Nested `def`s are scored
+    # independently (they're separate methods), so we don't descend into them.
+    def walk(node, multiplier, root: false)
+      return 0.0 if node.is_a?(Prism::DefNode) && !root
+
+      total = weight_for(node) * multiplier
+      child_multiplier = NESTING_NODES.include?(node.class) ? multiplier * DEPTH_FACTOR : multiplier
+      node.compact_child_nodes.each do |child|
+        total += walk(child, child_multiplier)
+      end
+      total
+    end
+
+    # The weight this node itself contributes (before the depth multiplier).
+    def weight_for(node)
+      case node
+      when Prism::CallNode
+        MAGIC_CALLS.fetch(node.name, BRANCH)
+      else
+        return BRANCH if BRANCH_NODES.include?(node.class)
+        return ASSIGNMENT if assignment?(node)
+        return CONDITION if CONDITION_NODES.include?(node.class)
+
+        0.0
+      end
+    end
+
+    # Every Prism assignment node class ends in "WriteNode" (plain writes,
+    # operator writes, ||=/&&= writes, multi-writes, and index/attr writes).
+    def assignment?(node)
+      node.class.name.end_with?("WriteNode")
+    end
+  end
+end

data/lib/moult/boundaries/packwerk.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "yaml"
+require_relative "../symbol_id"
+
+module Moult
+  module Boundaries
+    # The architecture-boundary adapter — Moult's reader of Packwerk's on-disk
+    # artifacts and the *only* file that names Packwerk. Everything downstream
+    # consumes the Moult-owned {Violation}/{Result} value objects, never a packwerk
+    # type, so the backend is swappable (the "swap, not rewrite" invariant).
+    #
+    # Like {Coverage} (which ingests SimpleCov/stdlib coverage *files*), this slice
+    # ingests packwerk's *files* rather than booting it: a live `bin/packwerk check`
+    # needs a bootable Rails/Zeitwerk app and emits only human prose / new-violation
+    # deltas, whereas packwerk *serialises every recorded violation* to stable,
+    # diffable `package_todo.yml` files. We read those (the package graph + the
+    # recorded violations packwerk already resolved via Zeitwerk) and own no part of
+    # the constant-resolution graph. Consequently Moult needs NO packwerk gem
+    # dependency (exactly as {Coverage} needs no simplecov). Live re-analysis — the
+    # fresh, line-level offense set — is deferred, the same way the Coverband and
+    # Flipper live stores are.
+    #
+    # The `package_todo.yml` shape we parse (packwerk's own serialization):
+    #
+    #   <defining-package>:            # the package that OWNS the referenced constant
+    #     "::Some::Constant":          # the constant crossing the boundary
+    #       violations:
+    #       - dependency               # one or more violation types
+    #       - privacy
+    #       files:
+    #       - path/to/referencing.rb   # the referencing files (root-relative)
+    #
+    # The file lives at `<referencing-package-dir>/package_todo.yml`, so the
+    # referencing package is the file's directory (root-relative; "." for the root
+    # package). packwerk reports violations at FILE granularity (no line numbers),
+    # which fixes this slice's join at path level.
+    module Packwerk
+      module_function
+
+      # A single recorded boundary violation: one referencing file crossing into one
+      # constant owned by another package, of one type. Path is root-relative.
+      Violation = Struct.new(:violation_type, :referencing_package, :defining_package, :constant, :path)
+
+      # The Moult-owned result of reading a project's packwerk artifacts. +configured+
+      # is false when the project has no `packwerk.yml` (not a packwerk project), in
+      # which case +violations+ is empty. +backend+/+backend_version+ originate here so
+      # "packwerk" stays isolated to this file.
+      Result = Struct.new(:violations, :backend, :backend_version, :configured)
+
+      # @param root [String] absolute analysis root
+      # @return [Result]
+      def detect(root:)
+        unless configured?(root)
+          return Result.new(violations: [], backend: "packwerk", backend_version: backend_version, configured: false)
+        end
+
+        violations = todo_files(root).flat_map { |file| violations_in(file, root) }
+        Result.new(violations: violations, backend: "packwerk", backend_version: backend_version, configured: true)
+      end
+
+      # A `packwerk.yml` at the root is the unambiguous "this is a packwerk project"
+      # marker (it is required for any packwerk run).
+      def configured?(root)
+        File.exist?(File.join(root, "packwerk.yml"))
+      end
+
+      def todo_files(root)
+        Dir.glob(File.join(root, "**", "package_todo.yml")).sort
+      end
+
+      # Parse one `package_todo.yml` into flat {Violation}s. The referencing package
+      # is the file's directory (root-relative). A malformed/empty file is skipped
+      # rather than crashing the whole run.
+      def violations_in(file, root)
+        referencing_package = package_name(File.dirname(file), root)
+        data = YAML.safe_load_file(file)
+        return [] unless data.is_a?(Hash)
+
+        data.flat_map do |defining_package, constants|
+          next [] unless constants.is_a?(Hash)
+          constants.flat_map do |constant, detail|
+            next [] unless detail.is_a?(Hash)
+            types = Array(detail["violations"])
+            paths = Array(detail["files"])
+            types.product(paths).map do |type, path|
+              Violation.new(
+                violation_type: type.to_s,
+                referencing_package: referencing_package,
+                defining_package: defining_package.to_s,
+                constant: constant.to_s,
+                path: path.to_s
+              )
+            end
+          end
+        end
+      rescue Psych::Exception
+        []
+      end
+
+      # Root-relative package name; "." for the root package (packwerk's convention).
+      def package_name(dir, root)
+        SymbolId.relative_path(dir, root)
+      end
+
+      # packwerk is not a Moult dependency, so its constant is normally absent; the
+      # version is recorded when it happens to be loaded, else nil (nullable in the
+      # contract). This is the only reference to the Packwerk constant in Moult.
+      def backend_version
+        defined?(::Packwerk::VERSION) ? ::Packwerk::VERSION : nil
+      end
+    end
+  end
+end

data/lib/moult/boundaries/severity.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Moult
+  module Boundaries
+    # The per-finding model for architecture boundaries — this slice's realisation
+    # of Moult's protected per-finding API. Unlike dead code, a packwerk violation
+    # is not a probabilistic guess: packwerk resolved the constant via Zeitwerk and
+    # verified it crosses a *declared* boundary, so the honest grade here is a
+    # SEVERITY classification, not a confidence. We never manufacture a fake 1.0
+    # confidence (which would carry no information); the finding's +confidence+ is
+    # null and {classify} assigns a severity by violation kind instead.
+    #
+    # This keeps the humility invariant in a different register: we still never
+    # overstate. A "severity" says how architecturally significant the *kind* of
+    # boundary crossing is — it does not assert the code is wrong, only that
+    # packwerk recorded a declared-boundary violation of that kind.
+    #
+    # {classify} is a pure function of the violation type — no IO, no packwerk
+    # objects — so it is pinned against hand-built inputs exactly like {ABC}, the
+    # coverage {Resolver}, and the duplication {Confidence} model. Drift is a bug.
+    module Severity
+      CATEGORY = "architecture_boundary"
+
+      # The ordered severity scale (least → most architecturally significant).
+      SCALE = %w[low medium high].freeze
+
+      # Pinned severity per packwerk violation type. Dependency and layer crossings
+      # break the *declared* dependency graph — the core architectural contract —
+      # so they rank highest. Privacy/visibility/folder_privacy are reaches past a
+      # package's public surface: real violations, but a narrower contract, so
+      # medium. An unrecognised type degrades to +low+ (we never drop it).
+      SEVERITY = {
+        "dependency" => "high",
+        "layer" => "high",
+        "privacy" => "medium",
+        "visibility" => "medium",
+        "folder_privacy" => "medium"
+      }.freeze
+
+      DEFAULT_SEVERITY = "low"
+
+      # Numeric weight per severity, consumed by the health composite to turn a set
+      # of violations into a per-file badness burden. Pinned alongside SEVERITY so
+      # the health boundaries component stays deterministic.
+      SEVERITY_WEIGHT = {"high" => 1.0, "medium" => 0.6, "low" => 0.3}.freeze
+
+      # One auditable note behind a classification. Mirrors the shared rule/detail
+      # reason shape, but a severity is categorical (not a delta-sum), so it carries
+      # no +delta+. Kept local so the boundaries slice does not couple to the
+      # dead-code or duplication Reason structs.
+      Reason = Struct.new(:rule, :detail) do
+        def to_h
+          {rule: rule.to_s, detail: detail}
+        end
+      end
+
+      # The graded result: a severity on {SCALE} and the reasons behind it.
+      Assessment = Struct.new(:severity, :reasons)
+
+      module_function
+
+      # @param violation_type [String] packwerk violation type, e.g. "dependency"
+      # @return [Assessment]
+      def classify(violation_type:)
+        severity = SEVERITY.fetch(violation_type, DEFAULT_SEVERITY)
+        Assessment.new(severity: severity, reasons: [Reason.new(rule: :"#{violation_type}_violation", detail: detail_for(violation_type, severity))])
+      end
+
+      def detail_for(violation_type, severity)
+        case violation_type
+        when "dependency"
+          "references a constant in a package this one does not declare a dependency on (#{severity})"
+        when "layer"
+          "depends across a declared architecture layer boundary (#{severity})"
+        when "privacy"
+          "references another package's private (non-public) constant (#{severity})"
+        when "visibility"
+          "references a package that does not list this one as visible_to (#{severity})"
+        when "folder_privacy"
+          "references a nested package outside the allowed folder scope (#{severity})"
+        else
+          "recorded packwerk boundary violation of an unrecognised type (#{severity})"
+        end
+      end
+    end
+  end
+end

data/lib/moult/boundaries.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Moult
+  # Orchestrates the architecture-boundaries analysis: it asks the {Boundaries::Packwerk}
+  # adapter for every recorded violation, groups them into findings, and grades each
+  # group through the pure {Boundaries::Severity} model. The result is a ranked
+  # {BoundariesReport} of confidence-null, severity-classified boundary violations —
+  # recorded facts, never claims that the code is wrong.
+  #
+  # This is the only layer that knows where the facts come from; {Severity} stays a
+  # pure function of the violation type so it can be pinned in isolation.
+  module Boundaries
+    module_function
+
+    # A finding is one group of violations sharing this identity (the same constant
+    # crossing the same package boundary in the same way); its occurrences are the
+    # referencing files.
+    GROUP_KEY = %i[referencing_package defining_package constant violation_type].freeze
+
+    # @param root [String] absolute analysis root
+    # @param min_severity [String, nil] drop findings below this severity (low<medium<high)
+    # @return [BoundariesReport]
+    def build_report(root:, min_severity: nil, git_ref: nil, generated_at: nil)
+      result = Packwerk.detect(root: root)
+
+      findings = group(result.violations).map { |key, violations| finding_for(key, violations) }
+      findings.select! { |f| meets?(f.severity, min_severity) } if min_severity
+      findings.sort_by! { |f| sort_key(f) }
+
+      BoundariesReport.new(
+        root: root,
+        findings: findings,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        backend: result.backend,
+        backend_version: result.backend_version,
+        configured: result.configured
+      )
+    end
+
+    def group(violations)
+      violations.group_by { |v| GROUP_KEY.map { |k| v[k] } }
+    end
+
+    def finding_for(key, violations)
+      referencing_package, defining_package, constant, violation_type = key
+      assessment = Severity.classify(violation_type: violation_type)
+      occurrences = violations
+        .map(&:path).uniq.sort
+        .map { |path| BoundariesReport::Occurrence.new(symbol_id: nil, path: path) }
+      BoundariesReport::Finding.new(
+        violation_type: violation_type,
+        severity: assessment.severity,
+        referencing_package: referencing_package,
+        defining_package: defining_package,
+        constant: constant,
+        reasons: assessment.reasons,
+        occurrences: occurrences
+      )
+    end
+
+    # Most-severe first, then a deterministic alphabetical tie-break so output is
+    # stable across runs.
+    def sort_key(finding)
+      [-Severity::SCALE.index(finding.severity), finding.violation_type,
+        finding.referencing_package, finding.defining_package, finding.constant]
+    end
+
+    def meets?(severity, floor)
+      Severity::SCALE.index(severity) >= Severity::SCALE.index(floor.to_s)
+    end
+  end
+end
+
+require_relative "boundaries/packwerk"
+require_relative "boundaries/severity"
+require_relative "boundaries_report"

data/lib/moult/boundaries_report.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult boundaries` (schema/boundaries.schema.json),
+  # sibling to {DuplicationReport}, {DeadCodeReport}, {CoverageReport} and {HealthReport}.
+  # It owns its own JSON envelope and leaves the other protected contracts untouched.
+  #
+  # Each {Finding} is one recorded architecture-boundary violation group. Unlike the
+  # dead-code/duplication contracts it carries +confidence: null+ (a packwerk violation
+  # is a recorded fact, not a probabilistic candidate) and a {Boundaries::Severity}
+  # classification instead — the honest per-finding grade for this slice. Nothing here
+  # asserts the code is *wrong*, only that packwerk recorded a declared-boundary crossing.
+  class BoundariesReport
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    # One referencing site of a violation group. +path+ (root-relative) is the join
+    # key into the health files[] roll-up. +symbol_id+ is the shared method-level
+    # join key, but it is NULL in this slice: packwerk's recorded violations are
+    # file-keyed (no line numbers), so there is no line to resolve an enclosing
+    # method. It is kept (nullable) for contract consistency with the duplication
+    # occurrence shape and to stay forward-compatible with line-level offenses.
+    Occurrence = Struct.new(:symbol_id, :path) do
+      def to_h
+        {symbol_id: symbol_id, path: path}
+      end
+    end
+
+    # One recorded boundary-violation group: a (referencing_package, defining_package,
+    # constant, violation_type) tuple referenced from one or more files. Carries its
+    # severity and reasons so the classification is auditable.
+    Finding = Struct.new(:violation_type, :severity, :referencing_package, :defining_package,
+      :constant, :reasons, :occurrences) do
+      def to_h
+        {
+          category: Boundaries::Severity::CATEGORY,
+          confidence: nil,
+          violation_type: violation_type,
+          severity: severity,
+          referencing_package: referencing_package,
+          defining_package: defining_package,
+          constant: constant,
+          reasons: reasons.map(&:to_h),
+          occurrences: occurrences.map(&:to_h)
+        }
+      end
+    end
+
+    attr_reader :root, :findings, :git_ref, :generated_at, :backend, :backend_version, :configured
+
+    # @param root [String] absolute analysis root
+    # @param findings [Array<Finding>] ranked, most-severe first
+    # @param backend [String] detector backend name (e.g. "packwerk")
+    # @param backend_version [String, nil] backend gem version, when known
+    # @param configured [Boolean] whether the project is packwerk-configured
+    def initialize(root:, findings:, git_ref: nil, generated_at: nil,
+      backend: "packwerk", backend_version: nil, configured: false)
+      @root = root
+      @findings = findings
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @backend = backend
+      @backend_version = backend_version
+      @configured = configured
+    end
+
+    # @return [Hash] aggregate counts across all violation groups
+    def summary
+      {
+        findings: findings.size,
+        violations: findings.sum { |f| f.occurrences.size },
+        by_type: tally { |f| f.violation_type },
+        by_severity: tally { |f| f.severity }
+      }
+    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,
+          detector: {
+            backend: backend,
+            backend_version: backend_version,
+            configured: configured
+          }
+        },
+        summary: summary,
+        findings: findings.map(&:to_h)
+      }
+    end
+
+    private
+
+    # Count findings grouped by the yielded key, occurrence-weighted so the totals
+    # match the +violations+ count (one violation = one referencing file).
+    def tally
+      findings.each_with_object(Hash.new(0)) do |finding, acc|
+        acc[yield(finding)] += finding.occurrences.size
+      end
+    end
+  end
+end

data/lib/moult/churn.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require_relative "git"
+
+module Moult
+  # Per-file change frequency from git history. "Change" means a commit that
+  # touched the file; the count is the number of such commits within the window.
+  #
+  # Decisions (v0.1):
+  #   * Window: the last 12 months by default ({DEFAULT_SINCE}), configurable via
+  #     +since+ (anything `git log --since` accepts, e.g. "2025-01-01"). All of
+  #     history over-weights long-lived files, so we bound it.
+  #   * Renames are NOT followed. `git log --follow` only works for a single
+  #     pathspec, so whole-repo rename tracking is out of scope; a renamed file
+  #     starts a fresh count under its new path.
+  #   * Outside a git repository, churn is empty (every file scores 0).
+  #
+  # Paths are reported relative to the repository root, as git emits them.
+  module Churn
+    DEFAULT_SINCE = "12 months ago"
+
+    module_function
+
+    # @param root [String] directory to run git in
+    # @param since [String] git --since boundary
+    # @return [Hash{String=>Integer}] path => commit count (default 0)
+    def collect(root:, since: DEFAULT_SINCE)
+      output = Git.log_name_only(root, since: since)
+      return empty_counts unless output
+
+      parse(output)
+    end
+
+    # Pure parser over `git log --name-only --pretty=format:` output. Counts how
+    # many lines (commits) mention each path.
+    # @param output [String]
+    # @return [Hash{String=>Integer}]
+    def parse(output)
+      counts = empty_counts
+      output.each_line(chomp: true) do |line|
+        next if line.empty?
+
+        counts[line] += 1
+      end
+      counts
+    end
+
+    def empty_counts
+      Hash.new(0)
+    end
+  end
+end

data/lib/moult/cli/boundaries_command.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult boundaries [PATH]` — list recorded architecture-boundary violations from
+    # the project's packwerk artifacts, classified by severity. Thin layer: parse
+    # options, drive the library, hand the {BoundariesReport} to a formatter.
+    # Report-only: exit 0 on success (including when the project is not
+    # packwerk-configured), non-zero only on error.
+    class BoundariesCommand
+      # @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, min_severity: nil, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult boundaries [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("--min-severity SEV", Boundaries::Severity::SCALE, "Hide findings below this severity: low, medium, high") { |v| options[:min_severity] = 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 = File.directory?(root) ? root : File.dirname(root)
+        report = Boundaries.build_report(
+          root: root_dir,
+          min_severity: options[:min_severity],
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601
+        )
+        note(options, report.configured ? "read packwerk artifacts: #{report.summary[:findings]} violation groups." : "no packwerk.yml found; not a packwerk project.")
+        report
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::BoundariesJson.render(report)
+        else Formatters::BoundariesTable.render(report)
+        end
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end