moult 0.1.0

data/lib/moult/cli/hotspots_command.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult hotspots [PATH]` — rank files by complexity x churn. Thin layer:
+    # parse options, drive the library, hand the {Report} to a formatter.
+    # Report-only: exit 0 on success, non-zero only on error.
+    class HotspotsCommand
+      DEFAULT_LIMIT = 20
+
+      # @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, limit: DEFAULT_LIMIT, since: Churn::DEFAULT_SINCE, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult hotspots [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("--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("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        # permute! processes options regardless of position, so `PATH` may come
+        # before or after flags; remaining non-options are left in argv.
+        @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)
+        files = File.directory?(root) ? Discovery.ruby_files(root) : [root]
+
+        unless Git.repo?(root_dir)
+          note(options, "#{root_dir} is not a git repository; churn is 0 for all files.")
+        end
+
+        Scoring.build_report(
+          root: root_dir,
+          files: files,
+          churn: Churn.collect(root: root_dir, since: options[:since]),
+          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])
+        )
+      end
+
+      def render(report, options)
+        limit = (options[:limit] && options[:limit] > 0) ? options[:limit] : nil
+        case options[:format]
+        when :json then Formatters::Json.render(report, limit: limit)
+        else Formatters::Table.render(report, limit: limit)
+        end
+      end
+
+      def window_label(since)
+        (since == Churn::DEFAULT_SINCE) ? "last 12 months" : "since #{since}"
+      end
+
+      # Only surface a concrete --since boundary when the user gave a fixed one;
+      # the relative default ("12 months ago") has no stable date.
+      def explicit_since(since)
+        (since == Churn::DEFAULT_SINCE) ? nil : since
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module Moult
+  # Thin command-line layer. Holds no analysis logic of its own: it parses
+  # options, delegates to the library, and hands the resulting {Report} to a
+  # formatter. Returns a process exit status (0 success, non-zero on error).
+  class CLI
+    # Subcommand => [require path, command class name]. Lazily required so a single
+    # command run never loads every analysis. Adding a slice is one entry here.
+    COMMANDS = {
+      "hotspots" => ["moult/cli/hotspots_command", :HotspotsCommand],
+      "deadcode" => ["moult/cli/dead_code_command", :DeadCodeCommand],
+      "coverage" => ["moult/cli/coverage_command", :CoverageCommand],
+      "duplication" => ["moult/cli/duplication_command", :DuplicationCommand],
+      "health" => ["moult/cli/health_command", :HealthCommand],
+      "boundaries" => ["moult/cli/boundaries_command", :BoundariesCommand],
+      "flags" => ["moult/cli/flags_command", :FlagsCommand],
+      "gate" => ["moult/cli/gate_command", :GateCommand]
+    }.freeze
+
+    # Tiny shared helpers for the command layer, so each command doesn't re-implement
+    # the same option plumbing. Lives on the always-loaded dispatcher.
+    module Support
+      module_function
+
+      # Resolve a PATH argument to its analysis root and the Ruby files under it:
+      # a directory analyses its tree, a single file analyses just itself.
+      # @return [Array(String, Array<String>)] [root_dir, files]
+      def discover(path)
+        if File.directory?(path)
+          [path, Discovery.ruby_files(path)]
+        else
+          [File.dirname(path), [path]]
+        end
+      end
+
+      # Build Rails entrypoint awareness, honouring a command's --[no-]rails option.
+      def build_rails(root_dir, files, enabled:)
+        return RailsConventions.new(rails: false) unless enabled
+
+        RailsConventions.build(root: root_dir, files: files)
+      end
+    end
+
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    # @return [Integer] process exit status
+    def run(argv)
+      argv = argv.dup
+
+      # Top-level flags that short-circuit before subcommand dispatch.
+      case argv.first
+      when "--version", "-v"
+        puts Moult::VERSION
+        return 0
+      when nil, "--help", "-h"
+        puts usage
+        return 0
+      end
+
+      dispatch(argv.shift, argv)
+    end
+
+    private
+
+    def dispatch(command, argv)
+      spec = COMMANDS[command]
+      unless spec
+        warn "moult: unknown command #{command.inspect}"
+        warn usage
+        return 1
+      end
+
+      require spec[0]
+      CLI.const_get(spec[1]).new.run(argv)
+    end
+
+    public
+
+    def usage
+      <<~USAGE
+        moult #{Moult::VERSION} — codebase intelligence for Ruby
+
+        Usage:
+          moult hotspots [PATH] [options]     Rank files by complexity x churn
+          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 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)
+          moult gate [PATH] [options]         Diff-aware PR risk gate: verdict over the changed code
+          moult --version                     Print version
+          moult --help                        Show this message
+      USAGE
+    end
+  end
+end

data/lib/moult/clones.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "flay"
+require_relative "symbol_id"
+
+module Moult
+  # The structural-clone detector — Moult's adapter over the +flay+ gem and the
+  # *only* file that names +Flay+. Everything downstream consumes the Moult-owned
+  # {Clones::Result} value object, never a flay type, so the backend is swappable
+  # (the "swap, not rewrite" invariant). This is the duplication-slice
+  # analogue of {Index} (rubydex) and {Coverage} (SimpleCov/stdlib).
+  #
+  # flay reports the *largest* duplicated S-expression node, grouping structurally
+  # equivalent code (literal values, variable/method/class names and whitespace are
+  # all ignored when hashing). Two distinctions it draws map onto our confidence
+  # grade:
+  #
+  # * +bonus+ truthy => the nodes are byte-for-byte IDENTICAL (names and all) —
+  #   the clearest copy-paste signal. We surface this as +kind: :identical+.
+  # * +bonus+ nil => structurally SIMILAR (same shape, differing names/literals) —
+  #   real duplication but weaker (could be parallel-by-design). +kind: :similar+.
+  #
+  # As of flay 2.14 the default parser is +Flay::NotRubyParser+, which parses with
+  # Prism (the same parser Moult uses); no parallel parser stack is pulled in.
+  module Clones
+    module_function
+
+    # One structurally-equivalent clone group. +node_type+ is flay's sexp type
+    # (e.g. :defn, :call, :class). +occurrences+ are the sites, in source order.
+    CloneSet = Struct.new(:structural_hash, :node_type, :kind, :mass, :occurrences)
+
+    # A single site of a clone group. +path+ is root-relative; +line+ is flay's
+    # reported start line (flay works at line granularity). +fuzzy+ is true only
+    # for a near-match node surfaced in fuzzy mode.
+    Occurrence = Struct.new(:path, :line, :fuzzy)
+
+    # The Moult-owned result of a detection run. Carries the provenance the
+    # contract records; +backend+/+backend_version+ originate here so "flay" stays
+    # isolated to this file.
+    Result = Struct.new(:sets, :backend, :backend_version, :min_mass, :fuzzy)
+
+    # @param root [String] absolute analysis root (occurrence paths are relative to it)
+    # @param files [Array<String>] absolute Ruby file paths to scan
+    # @param min_mass [Integer] flay's mass threshold; smaller fragments are ignored
+    # @param fuzzy [Boolean] also report near-matches (off by default: deterministic)
+    # @return [Result]
+    def detect(root:, files:, min_mass: DEFAULT_MIN_MASS, fuzzy: false)
+      sets = files.empty? ? [] : run_flay(files, min_mass, fuzzy).filter_map { |item| clone_set(item, root) }
+      Result.new(
+        sets: sets,
+        backend: "flay",
+        backend_version: backend_version,
+        min_mass: min_mass,
+        fuzzy: fuzzy
+      )
+    end
+
+    # flay's own default mass threshold; small enough to catch a duplicated method,
+    # large enough to skip incidental structural rhymes.
+    DEFAULT_MIN_MASS = 16
+
+    def run_flay(files, min_mass, fuzzy)
+      flay = Flay.new(Flay.default_options.merge(mass: min_mass, fuzzy: fuzzy))
+      flay.process(*files)
+      flay.analyze
+    rescue => e
+      raise Moult::Error, "flay duplication scan failed: #{e.class}: #{e.message}"
+    end
+
+    def clone_set(item, root)
+      occurrences = item.locations.map do |loc|
+        Occurrence.new(
+          path: SymbolId.relative_path(loc.file, root),
+          line: loc.line,
+          fuzzy: !loc.fuzzy.nil?
+        )
+      end
+      CloneSet.new(
+        structural_hash: item.structural_hash,
+        node_type: item.name.to_s,
+        kind: item.bonus ? :identical : :similar,
+        mass: item.mass,
+        occurrences: occurrences
+      )
+    end
+
+    def backend_version
+      defined?(Flay::VERSION) ? Flay::VERSION : nil
+    end
+  end
+end

data/lib/moult/cloud_upload.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Moult
+  # Builds the payload uploaded from CI to Moult Cloud out of a parsed
+  # `moult gate --format json` report.
+  #
+  # The gate report is already SOURCE-FREE by contract (a finding is
+  # category/path/symbol_id/line/value -- no code text), so this is not where
+  # "no source leaves the repo" is enforced; that is structural. This projection
+  # does two narrower jobs:
+  #   1. Allow-list the top-level keys -- defence-in-depth so a future formatter
+  #      addition cannot silently exfiltrate a new field.
+  #   2. Normalise analysis.root to "." -- the raw value is the absolute local
+  #      path, which leaks the developer's filesystem layout and is meaningless
+  #      to the cloud (it derives the repo from the CI OIDC token).
+  # The result stays valid against schema/gate.schema.json (root remains a string).
+  module CloudUpload
+    TOP_LEVEL_KEYS = %w[
+      schema_version tool analysis policy verdict reasons summary rules
+    ].freeze
+
+    def self.projection(report)
+      allowed = report.slice(*TOP_LEVEL_KEYS)
+      analysis = allowed["analysis"]
+      allowed["analysis"] = analysis.merge("root" => ".") if analysis.is_a?(Hash)
+      allowed
+    end
+  end
+end

data/lib/moult/confidence/rules.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Moult
+  module Confidence
+    # The named, ordered adjusters {Confidence.score} applies on top of the base
+    # score. Each is a small value object so a single rule can be tested in
+    # isolation and the set can be extended without touching the scorer.
+    #
+    # Direction is encoded in +delta+: positive raises confidence-of-death,
+    # negative lowers it. A rule may instead (or also) impose a +cap+ — an upper
+    # bound on the final confidence — used when a factor means "we genuinely
+    # cannot be sure", e.g. an unresolved index. No rule ever removes a finding:
+    # consistent with "never assert certain death", uncertainty *lowers*
+    # confidence and records a reason, it never hides the candidate.
+    module Rules
+      # @!attribute applies [Proc] ctx -> Boolean
+      # @!attribute delta   [Float] signed adjustment when it applies
+      # @!attribute cap     [Float, nil] optional upper bound on final confidence
+      # @!attribute detail  [String, Proc] human-readable reason (Proc gets ctx)
+      Rule = Struct.new(:name, :applies, :delta, :cap, :detail) do
+        def applies?(ctx)
+          applies.call(ctx)
+        end
+
+        def detail_for(ctx)
+          detail.respond_to?(:call) ? detail.call(ctx) : detail
+        end
+      end
+
+      DEFAULT_RULES = [
+        Rule.new(
+          name: :no_references,
+          applies: ->(c) { c.reference_count.to_i.zero? },
+          delta: 0.0,
+          detail: "no resolvable references found"
+        ),
+        Rule.new(
+          name: :has_test_only_references,
+          applies: ->(c) { c.test_only },
+          delta: -0.2,
+          detail: "only referenced from test/spec files"
+        ),
+        Rule.new(
+          name: :rails_entrypoint,
+          applies: ->(c) { !Array(c.rails_signals).empty? },
+          delta: -0.5,
+          detail: ->(c) { "Rails framework entrypoint: #{Array(c.rails_signals).map(&:detail).join("; ")}" }
+        ),
+        Rule.new(
+          name: :dynamic_dispatch_present,
+          applies: ->(c) { c.dynamic_dispatch },
+          delta: -0.35,
+          detail: "dynamic dispatch (send/define_method/method_missing/const_get/eval) present in file"
+        ),
+        # Constructors are invoked implicitly by `.new`, not by a call to
+        # `initialize`, so the index never records a reference. Universal Ruby
+        # (not Rails); kept narrow to this one near-certain implicit entrypoint.
+        Rule.new(
+          name: :implicit_constructor,
+          applies: ->(c) { c.kind == :method && c.name.to_s.end_with?("#initialize") },
+          delta: -0.4,
+          detail: "constructor invoked implicitly via .new"
+        ),
+        # A method that overrides/implements an ancestor's method is reachable
+        # 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.
+        Rule.new(
+          name: :overrides_ancestor,
+          applies: ->(c) { c.override_of },
+          delta: -0.4,
+          detail: ->(c) { "overrides #{c.override_of} (reachable via that interface)" }
+        ),
+        Rule.new(
+          name: :private_unused,
+          applies: ->(c) { c.kind == :method && c.visibility == :private && c.reference_count.to_i.zero? },
+          delta: 0.1,
+          detail: "private method with no caller in the codebase"
+        ),
+        Rule.new(
+          name: :public_api,
+          applies: ->(c) { c.kind == :method && c.visibility == :public },
+          delta: -0.1,
+          detail: "public method may be an external API entrypoint"
+        ),
+        Rule.new(
+          name: :deprecated_marked,
+          applies: ->(c) { c.deprecated },
+          delta: 0.1,
+          detail: "marked deprecated"
+        ),
+        Rule.new(
+          name: :index_unresolved,
+          applies: ->(c) { c.index_resolved == false },
+          delta: 0.0,
+          cap: 0.5,
+          detail: "index did not fully resolve; confidence capped"
+        ),
+        # Phase 3 runtime evidence. Applied last so it is the headline reason and,
+        # for the rescue case, caps over every static signal. Methods only — a
+        # constant's line runs at load regardless of use, so the resolver returns
+        # :untracked for constants and neither rule fires.
+        #
+        # runtime-cold corroborates a static candidate: the body never executed in
+        # the supplied run. Additive (not a cap) — coverage can be incomplete or
+        # stale (stale-detection deferred), so it raises confidence, never asserts.
+        Rule.new(
+          name: :runtime_cold,
+          applies: ->(c) { c.runtime == :cold },
+          delta: 0.2,
+          detail: "never executed in the supplied coverage run (runtime-cold corroborates)"
+        ),
+        # runtime-hot overrides: the symbol executed despite no resolvable static
+        # reference — the false positive static analysis missed (send / dynamic
+        # dispatch / metaprogramming). The cap drives it below default confidence
+        # gates while leaving a sliver, since coverage may be stale/incomplete.
+        Rule.new(
+          name: :runtime_hot,
+          applies: ->(c) { c.runtime == :hot },
+          delta: -0.6,
+          cap: 0.1,
+          detail: "executed at runtime (coverage) despite no static reference; rescued"
+        )
+      ].freeze
+    end
+  end
+end

data/lib/moult/confidence.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require_relative "span"
+
+module Moult
+  # The per-finding confidence model — one of Moult's two protected APIs (the
+  # other being the JSON output contract). It answers a single, deliberately
+  # humble question: *how likely is this definition to actually be dead?* It
+  # never asserts certain death (Moult's core principle); the highest a finding
+  # can score is still a confidence, and every contributing factor is recorded
+  # as a {Reason} so the judgement is auditable.
+  #
+  # {score} is a pure function of a {Context} of already-gathered facts: no IO,
+  # no rubydex, no Rails detection happens here. That keeps it trivially
+  # unit-testable and lets each {Rules::Rule} be exercised in isolation. The fact
+  # gathering lives in {DeadCode}; the conventions live in {RailsConventions}.
+  module Confidence
+    CATEGORY = "dead_code"
+
+    # Base likelihood before any rule fires, keyed by [kind, visibility]. A
+    # private method with no caller is the strongest candidate (nothing outside
+    # its class can reach it); public symbols are weakest because they are the
+    # natural API surface and the place metaprogramming/Rails reach in.
+    BASE = {
+      [:method, :private] => 0.75,
+      [:method, :protected] => 0.6,
+      [:method, :public] => 0.4,
+      [:constant, :private] => 0.6,
+      [:constant, :public] => 0.5
+    }.freeze
+    DEFAULT_BASE = 0.45
+
+    # The facts a finding is scored from. Assembled by {DeadCode#gather_context}.
+    Context = Struct.new(
+      :symbol_id, :kind, :name, :span, :path,
+      :visibility, :reference_count, :test_only,
+      :rails_signals,      # Array<RailsConventions::Signal>
+      :dynamic_dispatch,   # Boolean: metaprogramming present in the owning file
+      :override_of,        # String, nil: ancestor whose method this overrides
+      :deprecated,         # Boolean
+      :index_resolved,
+      :runtime             # Symbol, nil: :hot/:cold/:untracked from coverage (Phase 3)
+    )
+
+    # One auditable contribution to a finding's confidence.
+    Reason = Struct.new(:rule, :delta, :detail) do
+      def to_h
+        {rule: rule.to_s, delta: delta, detail: detail}
+      end
+    end
+
+    # A confidence-graded dead-code candidate. Carries its reasons so no claim
+    # is ever made without a recorded justification.
+    Finding = Struct.new(
+      :symbol_id, :kind, :name, :span, :path, :confidence, :category, :reasons, :runtime
+    ) do
+      def to_h
+        {
+          symbol_id: symbol_id,
+          kind: kind.to_s,
+          name: name,
+          span: span.to_h,
+          confidence: confidence,
+          category: category,
+          runtime: runtime&.to_s,
+          reasons: reasons.map(&:to_h)
+        }
+      end
+    end
+
+    module_function
+
+    # @param ctx [Context]
+    # @param rules [Array<Rules::Rule>] injectable for isolated testing
+    # @return [Finding]
+    def score(ctx, rules: Rules::DEFAULT_RULES)
+      base = BASE.fetch([ctx.kind, ctx.visibility], DEFAULT_BASE)
+      reasons = [Reason.new(rule: :base_score, delta: base, detail: "base for #{ctx.kind}/#{ctx.visibility}")]
+      caps = []
+
+      rules.each do |rule|
+        next unless rule.applies?(ctx)
+        reasons << Reason.new(rule: rule.name, delta: rule.delta, detail: rule.detail_for(ctx))
+        caps << rule.cap if rule.cap
+      end
+
+      raw = reasons.sum(&:delta)
+      bounded = caps.empty? ? raw : [raw, caps.min].min
+      confidence = bounded.clamp(0.0, 1.0).round(2)
+
+      Finding.new(
+        symbol_id: ctx.symbol_id,
+        kind: ctx.kind,
+        name: ctx.name,
+        span: ctx.span,
+        path: ctx.path,
+        confidence: confidence,
+        category: CATEGORY,
+        reasons: reasons,
+        runtime: ctx.runtime
+      )
+    end
+  end
+end
+
+require_relative "confidence/rules"

data/lib/moult/coverage/resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Moult
+  module Coverage
+    # The line->symbol resolver: turns line-keyed coverage into a per-symbol
+    # runtime classification. This is the one genuinely novel
+    # component, so its rules are precise and fixture-pinned — drift is a bug,
+    # exactly like the ABC metric.
+    #
+    # For a method definition spanning +span.start_line..span.end_line+ in a
+    # tracked file, it inspects the *body* lines and returns:
+    #
+    # * +:hot+       — at least one executable body line was executed
+    # * +:cold+      — the file is tracked, body has executable lines, none ran
+    # * +:untracked+ — no usable signal (see below)
+    #
+    # The defining rule is that the +def+ signature line is EXCLUDED: stdlib
+    # +Coverage+ counts it at definition (load) time, not per call, so counting
+    # it would mark every loaded method hot. Only the body reflects real calls.
+    module Resolver
+      module_function
+
+      # @param dataset [Dataset]
+      # @param path [String] root-relative path (a symbol_id component)
+      # @param span [Span] 1-based definition span
+      # @param kind [Symbol] :method or :constant
+      # @return [Symbol] :hot, :cold, or :untracked
+      def classify(dataset, path:, span:, kind:)
+        # A constant's only line is its assignment, executed at load regardless
+        # of whether the constant is ever read — so it carries no runtime signal.
+        return :untracked unless kind == :method
+        lines = dataset.entries[path]
+        return :untracked unless lines
+
+        executable = body_values(lines, span)
+        # No executable body line to judge: one-line methods (def f = x), empty
+        # methods, abstract stubs. Their only line is the def line (load-time
+        # coverage), so they are genuinely unclassifiable in :lines mode.
+        return :untracked if executable.empty?
+
+        executable.any?(&:positive?) ? :hot : :cold
+      end
+
+      # Coverage values for the executable (non-nil) body lines, excluding the
+      # +def+ signature line at +span.start_line+. The +end+ line and blanks are
+      # nil and so fall out naturally.
+      # @return [Array<Integer>]
+      def body_values(lines, span)
+        first = span.start_line + 1
+        last = span.end_line
+        return [] if first > last
+        (first..last).filter_map { |line| lines[line - 1] }
+      end
+    end
+  end
+end