moult 0.1.0

data/lib/moult/health_report.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult health` (schema/health.schema.json),
+  # sibling to {DuplicationReport}, {DeadCodeReport} and {CoverageReport}. It owns
+  # its own JSON envelope and leaves the other protected contracts untouched.
+  #
+  # The composite is a confidence-graded health SIGNAL, never a verdict: it records
+  # every contributing component (and every skipped/errored one) plus the reasons
+  # behind each sub-score, so the headline number is auditable. Nothing here asserts
+  # a pass/fail — that gate is Phase 4.
+  class HealthReport
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    # One component of the composite, as serialized. +present+ false means the
+    # analysis was skipped (e.g. no --coverage) or errored; then +score+ and
+    # +normalized_weight+ are null and +diagnostic+ says why.
+    ComponentView = Struct.new(:name, :category, :present, :score, :weight,
+      :normalized_weight, :summary, :reasons, :diagnostic) do
+      def to_h
+        {
+          name: name,
+          category: category,
+          present: present,
+          score: score,
+          weight: weight,
+          normalized_weight: normalized_weight,
+          summary: summary,
+          reasons: reasons.map(&:to_h),
+          diagnostic: diagnostic
+        }
+      end
+    end
+
+    # One file's rolled-up health and the join keys that contributed to it.
+    # +components+ is a compact name => sub-score map (present components only).
+    FileView = Struct.new(:path, :score, :grade, :components, :symbol_ids, :symbol_count) do
+      def to_h
+        {
+          path: path,
+          score: score,
+          grade: grade,
+          components: components,
+          symbol_ids: symbol_ids,
+          symbol_count: symbol_count
+        }
+      end
+    end
+
+    attr_reader :root, :score, :grade, :components, :files, :git_ref, :generated_at,
+      :coverage_source, :churn_window, :churn_since
+
+    # @param root [String] absolute analysis root
+    # @param score [Float, nil] composite health in [0, 1]; nil when no component ran
+    # @param grade [String, nil] letter grade, or nil
+    # @param components [Array<ComponentView>] one per considered analysis, fixed order
+    # @param files [Array<FileView>] per-file roll-up, least-healthy first
+    # @param coverage_source [Coverage::Source, nil] provenance when coverage was merged
+    def initialize(root:, score:, grade:, components:, files:, git_ref: nil, generated_at: nil,
+      coverage_source: nil, churn_window: nil, churn_since: nil)
+      @root = root
+      @score = score
+      @grade = grade
+      @components = components
+      @files = files
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @coverage_source = coverage_source
+      @churn_window = churn_window
+      @churn_since = churn_since
+    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,
+          coverage: coverage_source&.to_h,
+          churn: {window: churn_window, since: churn_since}
+        },
+        overall: {
+          score: score,
+          grade: grade,
+          components_present: components.count(&:present),
+          components_total: components.size,
+          files_total: files.size
+        },
+        components: components.map(&:to_h),
+        files: files.map(&:to_h)
+      }
+    end
+  end
+end

data/lib/moult/index.rb

@@ -0,0 +1,228 @@
+# frozen_string_literal: true
+
+require "rubydex"
+require_relative "span"
+require_relative "symbol_id"
+
+module Moult
+  # The definition/reference index — Moult's adapter over the +rubydex+ gem and
+  # the *only* file that names +Rubydex+. Everything downstream consumes the
+  # Moult-owned {Index::Definition} value object, never a rubydex type, so the
+  # backend is swappable (the "swap, not rewrite" invariant).
+  #
+  # rubydex has two quirks this adapter normalises away (see test/test_index.rb):
+  #
+  # * Its locations are 0-based; Moult/Prism are 1-based. We add 1 to line
+  #   numbers so dead-code symbol ids line up with {Scoring}'s hotspot ids.
+  # * Method references are not resolved to their target declaration (only
+  #   constants are). So a method is considered "referenced" when its bare name
+  #   appears anywhere in the call-site collection. This is deliberately
+  #   conservative: a name collision can only *hide* a dead method, never invent
+  #   a false positive — the safe direction for a confidence-graded tool.
+  class Index
+    # A definition site that is a candidate for the dead-code analysis. All
+    # fields are Moult-owned; no rubydex object leaks past this struct.
+    #
+    # @!attribute kind        [Symbol] :method or :constant
+    # @!attribute visibility  [Symbol] :public, :private, :protected
+    # @!attribute singleton   [Boolean] true for Class.method / constants
+    # @!attribute reference_count [Integer] resolvable usages of this definition
+    # @!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
+    Definition = Struct.new(
+      :symbol_id, :kind, :name, :unqualified_name, :owner,
+      :visibility, :singleton, :span, :path,
+      :reference_count, :reference_paths, :override_of
+    )
+
+    BUILTIN_SCHEME = "file:"
+
+    class << self
+      # @param root [String] absolute analysis root
+      # @param paths [Array<String>] absolute paths of Ruby files to index
+      # @return [Index]
+      def build(root:, paths:)
+        graph = Rubydex::Graph.new
+        graph.index_all(Array(paths))
+        graph.resolve
+        new(graph: graph, root: root)
+      rescue => e
+        raise Moult::Error, "rubydex indexing failed: #{e.class}: #{e.message}"
+      end
+
+      # Whether the rubydex backend is loadable. Always true once the gem is a
+      # hard dependency, but kept so live integration tests can skip cleanly.
+      def available?
+        require "rubydex"
+        true
+      rescue LoadError
+        false
+      end
+    end
+
+    def initialize(graph:, root:)
+      @graph = graph
+      # rubydex reports canonical (symlink-resolved) paths, so the root must be
+      # canonicalised too or workspace filtering misses everything on systems
+      # where e.g. /tmp -> /private/tmp.
+      @root = File.realpath(root.to_s)
+    rescue Errno::ENOENT
+      @root = root.to_s
+    end
+
+    # @return [Array<Index::Definition>] method + constant definition sites
+    #   defined within the workspace, each with its resolved reference count.
+    def definitions
+      @definitions ||= method_definitions + constant_definitions
+    end
+
+    def resolved?
+      true
+    end
+
+    # @return [Array<String>] human-readable index diagnostics (non-fatal).
+    def diagnostics
+      @graph.diagnostics.map(&:to_s)
+    rescue
+      []
+    end
+
+    private
+
+    def method_definitions
+      @graph.declarations.select { |d| d.is_a?(Rubydex::Method) }.flat_map do |decl|
+        name = normalize_name(decl.name)
+        unqualified = strip_signature(decl.unqualified_name)
+        sites = method_call_sites[unqualified]
+        override = override_source(decl)
+        in_workspace_definitions(decl).map do |defn, span, rel|
+          Definition.new(
+            symbol_id: SymbolId.for(path: rel, start_line: span.start_line, fqname: name),
+            kind: :method,
+            name: name,
+            unqualified_name: unqualified,
+            owner: decl.owner&.name,
+            visibility: visibility_of(decl),
+            singleton: !name.include?("#"),
+            span: span,
+            path: rel,
+            reference_count: sites.size,
+            reference_paths: sites.compact.uniq,
+            override_of: override
+          )
+        end
+      end
+    end
+
+    def constant_definitions
+      @graph.declarations.select { |d| d.is_a?(Rubydex::Constant) }.flat_map do |decl|
+        refs = constant_reference_paths(decl)
+        in_workspace_definitions(decl).map do |defn, span, rel|
+          Definition.new(
+            symbol_id: SymbolId.for(path: rel, start_line: span.start_line, fqname: decl.name),
+            kind: :constant,
+            name: decl.name,
+            unqualified_name: strip_signature(decl.unqualified_name),
+            owner: decl.owner&.name,
+            visibility: visibility_of(decl),
+            singleton: true,
+            span: span,
+            path: rel,
+            reference_count: refs.size,
+            reference_paths: refs.compact.uniq,
+            override_of: nil
+          )
+        end
+      end
+    end
+
+    # rubydex does not resolve method references to a target, so we index every
+    # call site by its bare name: { "perform" => ["app/jobs/x.rb", ...] }.
+    def method_call_sites
+      @method_call_sites ||= @graph.method_references.each_with_object(Hash.new { |h, k| h[k] = [] }) do |ref, acc|
+        acc[ref.name.to_s] << workspace_relative(ref.location)
+      end
+    end
+
+    def constant_reference_paths(decl)
+      decl.references.map { |ref| workspace_relative(ref.location) }
+    rescue
+      []
+    end
+
+    # @return [Array<[definition, Span, rel_path]>] only sites inside the workspace
+    def in_workspace_definitions(decl)
+      decl.definitions.filter_map do |defn|
+        loc = defn.location
+        next unless in_workspace?(loc)
+        [defn, span_from(loc), workspace_relative(loc)]
+      end
+    end
+
+    def in_workspace?(location)
+      return false unless location
+      uri = location.uri
+      return false unless uri&.start_with?(BUILTIN_SCHEME)
+      file_path(location)&.start_with?(@root) || false
+    end
+
+    def workspace_relative(location)
+      path = file_path(location)
+      return nil unless path&.start_with?(@root)
+      SymbolId.relative_path(path, @root)
+    end
+
+    def file_path(location)
+      return nil unless location&.uri&.start_with?(BUILTIN_SCHEME)
+      location.to_file_path
+    rescue
+      nil
+    end
+
+    # rubydex lines are 0-based; Moult/Prism are 1-based. Columns already align.
+    def span_from(location)
+      Span.new(
+        start_line: location.start_line + 1,
+        start_column: location.start_column,
+        end_line: location.end_line + 1,
+        end_column: location.end_column
+      )
+    end
+
+    # The FQ name of the nearest ancestor (superclass or included module) that
+    # defines a method of the same name — meaning this definition overrides or
+    # implements it and is reachable through that ancestor's interface
+    # (polymorphic dispatch). nil when it overrides nothing in-workspace. Members
+    # are keyed by their signature form ("call()"), so the raw unqualified_name
+    # is the correct lookup key. External ancestors (gems) are only visible when
+    # their source has been indexed.
+    def override_source(decl)
+      owner = decl.owner
+      return nil unless owner
+      member_name = decl.unqualified_name
+      owner.ancestors.each do |ancestor|
+        next if ancestor.name == owner.name
+        return ancestor.name unless ancestor.member(member_name).nil?
+      end
+      nil
+    rescue
+      nil
+    end
+
+    def visibility_of(decl)
+      vis = decl.visibility if decl.respond_to?(:visibility)
+      %i[public private protected].include?(vis) ? vis : :public
+    end
+
+    # "Shop::Widget#helper()" => "Shop::Widget#helper";
+    # singleton "Acme::Service::<Service>#build()" => "Acme::Service.build"
+    def normalize_name(raw)
+      strip_signature(raw.to_s).sub(/::<[^>]+>#/, ".")
+    end
+
+    def strip_signature(raw)
+      raw.to_s.sub(/\(.*\z/m, "")
+    end
+  end
+end

data/lib/moult/parser.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "prism"
+require_relative "span"
+
+module Moult
+  # A single method definition discovered by parsing. Internal to the analysis
+  # pipeline (not the serialized {Report::Method}); it retains the Prism node so
+  # the ABC metric can walk the method's subtree.
+  #
+  # +name+ is the *lexical* fully-qualified name (Class#method / Class.method),
+  # derived from the written module/class nesting only. Constant resolution
+  # (Zeitwerk, includes, reopened constants) is deliberately out of Phase 1.
+  MethodDef = Struct.new(:name, :span, :node)
+
+  # Pure parsing layer: source -> list of {MethodDef}. No IO beyond optionally
+  # reading a file; no git, no scoring. Trivially unit-testable on snippets.
+  module Parser
+    module_function
+
+    # @param path [String] file to read and parse
+    # @return [Array<MethodDef>]
+    def parse_file(path)
+      parse_source(File.read(path))
+    end
+
+    # @param source [String] Ruby source
+    # @return [Array<MethodDef>] in source order
+    def parse_source(source)
+      result = Prism.parse(source)
+      visitor = Visitor.new
+      result.value.accept(visitor)
+      visitor.methods
+    end
+
+    # Walks the AST tracking lexical class/module nesting and `class << self`
+    # context so each def gets a fully-qualified lexical name.
+    class Visitor < Prism::Visitor
+      attr_reader :methods
+
+      def initialize
+        @namespace = []         # stack of constant-path strings, e.g. ["A", "B::C"]
+        @singleton_context = [] # truthy frame == inside `class << self`
+        @methods = []
+        super
+      end
+
+      def visit_class_node(node)
+        @namespace.push(node.constant_path.slice)
+        super
+        @namespace.pop
+      end
+
+      def visit_module_node(node)
+        @namespace.push(node.constant_path.slice)
+        super
+        @namespace.pop
+      end
+
+      def visit_singleton_class_node(node)
+        # `class << self` makes nested defs singleton (class) methods of the
+        # enclosing namespace. Other `class << obj` forms are visited but not
+        # specially qualified.
+        @singleton_context.push(node.expression.is_a?(Prism::SelfNode))
+        super
+        @singleton_context.pop
+      end
+
+      def visit_def_node(node)
+        @methods << MethodDef.new(
+          name: qualified_name(node),
+          span: span_for(node),
+          node: node
+        )
+        super
+      end
+
+      private
+
+      def qualified_name(node)
+        singleton = !node.receiver.nil? || @singleton_context.last
+        separator = singleton ? "." : "#"
+        qualifier = @namespace.join("::")
+        return "#{separator}#{node.name}" if qualifier.empty? && singleton
+        return node.name.to_s if qualifier.empty?
+
+        "#{qualifier}#{separator}#{node.name}"
+      end
+
+      def span_for(node)
+        loc = node.location
+        Span.new(
+          start_line: loc.start_line,
+          start_column: loc.start_column,
+          end_line: loc.end_line,
+          end_column: loc.end_column
+        )
+      end
+    end
+  end
+end

data/lib/moult/rails_conventions.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require_relative "symbol_scanner"
+
+module Moult
+  # Models the Rails entrypoint conventions that make framework-invoked code
+  # *look* unused. In Rails most "uncalled" methods are reached by convention
+  # (controller actions via routing, jobs via `#perform`) or by symbol-based
+  # DSLs (`before_action :authenticate`) that no static call site references.
+  #
+  # This layer never hides a finding (per Moult's core principle,
+  # metaprogramming/conventions must *lower* confidence, never silently hide). It only emits {Signal}s that
+  # the +:rails_entrypoint+ confidence rule turns into a strong, *explained*
+  # downward adjustment. A genuinely dead controller action therefore still
+  # appears — just sorted low — rather than being asserted alive.
+  #
+  # Scope (Tier A): controller/mailer actions, helpers, job `#perform`, symbol-
+  # DSL callbacks, serializers, initializers. Classes/modules are not flagged at
+  # all (only methods and non-class constants are candidates), which sidesteps
+  # STI/Zeitwerk false positives for this slice. Route-file and view-template
+  # resolution are deferred.
+  class RailsConventions
+    Signal = Struct.new(:rule, :detail)
+
+    CONTROLLER = %r{(\A|/)app/controllers/.+_controller\.rb\z}
+    MAILER = %r{(\A|/)app/mailers/.+\.rb\z}
+    HELPER = %r{(\A|/)app/helpers/.+\.rb\z}
+    JOB = %r{(\A|/)app/jobs/.+\.rb\z}
+    SERIALIZER = %r{(\A|/)app/serializers/.+\.rb\z}
+    INITIALIZER = %r{(\A|/)config/initializers/.+\.rb\z}
+
+    PERFORM_METHODS = %w[perform perform_async perform_later perform_now].freeze
+
+    class << self
+      # @param root [String] absolute analysis root
+      # @param files [Array<String>] absolute Ruby file paths (for DSL scan)
+      # @return [RailsConventions]
+      def build(root:, files:)
+        rails = rails_app?(root)
+        refs = rails ? collect_dsl_references(files) : Set.new
+        new(rails: rails, dsl_references: refs)
+      end
+
+      def rails_app?(root)
+        return true if File.file?(File.join(root, "config", "application.rb"))
+        File.directory?(File.join(root, "app")) && gemfile_mentions_rails?(root)
+      end
+
+      def gemfile_mentions_rails?(root)
+        gemfile = File.join(root, "Gemfile")
+        return false unless File.file?(gemfile)
+        File.foreach(gemfile).any? { |line| line =~ /^\s*gem\s+["'](rails|railties)["']/ }
+      rescue
+        false
+      end
+
+      def collect_dsl_references(files)
+        files.each_with_object(Set.new) do |path, set|
+          SymbolScanner.scan_file(path).each { |name| set << name }
+        rescue
+          next
+        end
+      end
+    end
+
+    # @param rails [Boolean] whether the project is a Rails app
+    # @param dsl_references [Set<String>] method names referenced via DSL symbols
+    def initialize(rails:, dsl_references: Set.new)
+      @rails = rails
+      @dsl_references = dsl_references
+    end
+
+    def rails?
+      @rails
+    end
+
+    # @param definition [Index::Definition]
+    # @return [Array<Signal>] matched entrypoint conventions (empty if none / not Rails)
+    def signals_for(definition)
+      return [] unless @rails
+
+      [path_signal(definition), symbol_signal(definition)].compact
+    end
+
+    private
+
+    def path_signal(definition)
+      return nil unless definition.kind == :method
+      path = definition.path.to_s
+
+      case path
+      when CONTROLLER
+        action_signal(definition, :rails_controller_action, "public action in #{path}")
+      when MAILER
+        action_signal(definition, :rails_mailer_action, "public mailer action in #{path}")
+      when HELPER
+        Signal.new(rule: :rails_helper, detail: "helper method in #{path}")
+      when JOB
+        if PERFORM_METHODS.include?(definition.unqualified_name)
+          Signal.new(rule: :rails_job_perform, detail: "job entrypoint #{definition.unqualified_name} in #{path}")
+        end
+      when SERIALIZER
+        Signal.new(rule: :rails_serializer, detail: "serializer method in #{path}")
+      when INITIALIZER
+        Signal.new(rule: :rails_initializer, detail: "runs at boot in #{path}")
+      end
+    end
+
+    # Public instance methods of controllers/mailers are framework-invoked
+    # actions; private/protected ones are helpers reached only via call or
+    # symbol-DSL, so they are left to the normal rules.
+    def action_signal(definition, rule, detail)
+      return nil unless definition.visibility == :public
+      Signal.new(rule: rule, detail: detail)
+    end
+
+    def symbol_signal(definition)
+      return nil unless definition.kind == :method
+      return nil unless @dsl_references.include?(definition.unqualified_name)
+
+      Signal.new(rule: :rails_callback, detail: "referenced as a DSL symbol (e.g. before_action :#{definition.unqualified_name})")
+    end
+  end
+end

data/lib/moult/report.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Moult
+  # The in-memory result model and the source of the typed JSON output
+  # contract. This is one of Moult's two protected APIs (the other being the
+  # per-finding confidence model). Every analysis must be swappable behind this
+  # shape without changing it; both formatters render from this object so they
+  # cannot drift.
+  #
+  # The model reserves +confidence+ and +category+ on every finding even though
+  # Phase 1 never populates them: findings are confidence-graded, never asserted
+  # as certain death. Phases 2+ fill these in without a schema_version bump.
+  class Report
+    # Bump only on a breaking change to the serialized shape.
+    SCHEMA_VERSION = 1
+
+    attr_reader :root, :git_ref, :generated_at, :churn_window, :churn_since, :hotspots
+
+    # @param root [String] absolute path the analysis was rooted at
+    # @param hotspots [Array<Hotspot>] ranked, highest score first
+    # @param git_ref [String, nil] HEAD sha when run inside a repo
+    # @param generated_at [String, nil] ISO8601 timestamp
+    # @param churn_window [String, nil] human description of the churn window
+    # @param churn_since [String, nil] the resolved --since boundary (ISO8601 date)
+    def initialize(root:, hotspots:, git_ref: nil, generated_at: nil, churn_window: nil, churn_since: nil)
+      @root = root
+      @hotspots = hotspots
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @churn_window = churn_window
+      @churn_since = churn_since
+    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,
+          churn: {window: churn_window, since: churn_since}
+        },
+        hotspots: hotspots.map(&:to_h)
+      }
+    end
+
+    # One ranked file.
+    class Hotspot
+      attr_reader :path, :score, :complexity, :churn, :methods, :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)
+        @path = path
+        @score = score
+        @complexity = complexity
+        @churn = churn
+        @methods = methods
+        @confidence = confidence
+        @category = category
+      end
+
+      # The single worst method in the file, for table drill-down.
+      def worst_method
+        methods.first
+      end
+
+      def to_h
+        {
+          path: path,
+          score: score,
+          complexity: complexity,
+          churn: churn,
+          confidence: confidence,
+          category: category,
+          methods: methods.map(&:to_h)
+        }
+      end
+    end
+
+    # One method definition with its complexity.
+    class Method
+      attr_reader :symbol_id, :name, :span, :abc, :confidence, :category
+
+      # @param symbol_id [String] stable join key: "<path>:<start_line>:<fqname>"
+      # @param name [String] lexical fully-qualified name (Class#method / Class.method)
+      # @param span [Span] definition source range
+      # @param abc [Float] flog-style weighted ABC score
+      def initialize(symbol_id:, name:, span:, abc:, confidence: nil, category: nil)
+        @symbol_id = symbol_id
+        @name = name
+        @span = span
+        @abc = abc
+        @confidence = confidence
+        @category = category
+      end
+
+      def to_h
+        {
+          symbol_id: symbol_id,
+          name: name,
+          span: span.to_h,
+          abc: abc,
+          confidence: confidence,
+          category: category
+        }
+      end
+    end
+  end
+end