moult 0.1.0

data/lib/moult/scoring.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Moult
+  # Aggregates the per-method ABC and per-file churn into a ranked {Report}.
+  #
+  # File complexity is the sum of its methods' ABC; the file score is
+  # complexity x churn. This raw product is dominated by outliers - acceptable
+  # for v0.1, but {combine} is isolated so a normalisation strategy (log, rank,
+  # z-score) can drop in later without touching the rest of the pipeline.
+  #
+  # Files with no methods (or only zero-scoring ones) are omitted: they cannot
+  # be a complexity hotspot. Ranking is score-descending, with complexity then
+  # path as deterministic tie-breakers (so 0-churn files - e.g. outside a repo -
+  # still order by complexity rather than arbitrarily).
+  module Scoring
+    DEFAULT_WORST_METHODS = 3
+
+    module_function
+
+    # @param root [String] absolute analysis root
+    # @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
+    # @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)
+      hotspots = files.filter_map do |abs|
+        hotspot_for(abs, root: root, churn: churn, worst_methods: worst_methods)
+      end
+      hotspots.sort_by! { |h| [-h.score, -h.complexity, h.path] }
+
+      Report.new(
+        root: root,
+        hotspots: hotspots,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        churn_window: churn_window,
+        churn_since: churn_since
+      )
+    end
+
+    # @return [Report::Hotspot, nil] nil when the file has no scoring methods
+    def hotspot_for(abs, root:, churn:, worst_methods:)
+      rel = relative_path(abs, root)
+      methods = Parser.parse_file(abs).map { |m| build_method(m, rel) }
+      complexity = methods.sum(0.0, &:abc)
+      return nil if complexity.zero?
+
+      churn_count = churn[rel]
+      kept = methods.sort_by { |m| -m.abc }.first(worst_methods)
+
+      Report::Hotspot.new(
+        path: rel,
+        score: combine(complexity, churn_count).round(2),
+        complexity: complexity.round(2),
+        churn: churn_count,
+        methods: kept
+      )
+    end
+
+    # The v0.1 scoring rule. Swap-point for future normalisation.
+    # @return [Numeric]
+    def combine(complexity, churn)
+      complexity * churn
+    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),
+        name: method_def.name,
+        span: method_def.span,
+        abc: ABC.score(method_def.node)
+      )
+    end
+
+    def relative_path(abs, root)
+      SymbolId.relative_path(abs, root)
+    end
+  end
+end

data/lib/moult/span.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Moult
+  # A source location range for a definition. Lines are 1-based, columns are
+  # 0-based, matching Prism's location offsets. Part of the protected JSON
+  # contract and a component of a method's Phase 3 coverage join key.
+  Span = Struct.new(:start_line, :start_column, :end_line, :end_column) do
+    def to_h
+      {
+        start_line: start_line,
+        start_column: start_column,
+        end_line: end_line,
+        end_column: end_column
+      }
+    end
+  end
+end

data/lib/moult/symbol_id.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module Moult
+  # Builds the stable symbol id used as the cross-analysis join key:
+  # "<path>:<start_line>:<fqname>" (path relative to the analysis root,
+  # start_line 1-based). Shared by {Scoring} (hotspots) and {Index} (dead code)
+  # so the two analyses mint identical ids for the same definition and the
+  # Phase 3 coverage merge can join them. Centralised here so the format cannot
+  # drift between producers.
+  module SymbolId
+    module_function
+
+    # @param path [String] path relative to the analysis root
+    # @param start_line [Integer] 1-based definition line
+    # @param fqname [String] fully-qualified lexical name (Class#method / Class.method)
+    # @return [String]
+    def for(path:, start_line:, fqname:)
+      "#{path}:#{start_line}:#{fqname}"
+    end
+
+    # @param abs [String] absolute path
+    # @param root [String] absolute analysis root
+    # @return [String] path relative to root
+    def relative_path(abs, root)
+      Pathname.new(abs).relative_path_from(Pathname.new(root)).to_s
+    end
+  end
+end

data/lib/moult/symbol_scanner.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "prism"
+
+module Moult
+  # Collects method names that are referenced *as symbols* passed to Rails-style
+  # DSL methods — `before_action :authenticate`, `validate :check`,
+  # `helper_method :current_user`, `delegate :name, to: :user`. rubydex's
+  # reference index only sees real call sites, so these symbol arguments look
+  # like nothing references the method and it would be a false-positive
+  # dead-code candidate. This scanner harvests them so {RailsConventions} can
+  # treat the named methods as live.
+  #
+  # It is intentionally name-based and lexically scoped to the enclosing
+  # class/module: it returns the set of bare method names referenced by DSL
+  # symbols in a file, qualified by the surrounding namespace where known. Over-
+  # collecting is safe — a spurious "reference" only lowers a finding's
+  # confidence, it can never invent a finding.
+  module SymbolScanner
+    # DSL methods whose Symbol arguments name a method of the surrounding class.
+    CALLBACK_DSL = %w[
+      before_action after_action around_action
+      append_before_action prepend_before_action
+      skip_before_action skip_after_action skip_around_action
+      before_filter after_filter around_filter
+      before_save after_save before_create after_create
+      before_update after_update before_destroy after_destroy
+      before_validation after_validation
+      after_commit after_rollback after_initialize after_find
+      before_action_callback
+      validate validates_each
+      helper_method
+      scope delegate
+    ].freeze
+
+    module_function
+
+    # @param source [String] Ruby source
+    # @return [Array<String>] referenced names: bare ("authenticate") and, where
+    #   a lexical namespace is known, qualified ("Foo::Bar#authenticate").
+    def scan_source(source)
+      result = Prism.parse(source)
+      visitor = Visitor.new
+      result.value.accept(visitor)
+      visitor.referenced_names.to_a
+    end
+
+    # @param path [String]
+    # @return [Array<String>]
+    def scan_file(path)
+      scan_source(File.read(path))
+    end
+
+    # Walks the tree tracking lexical nesting (mirroring {Parser::Visitor}) so a
+    # collected symbol can be attributed to its enclosing class.
+    class Visitor < Prism::Visitor
+      attr_reader :referenced_names
+
+      def initialize
+        @namespace = []
+        @referenced_names = []
+        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_call_node(node)
+        collect(node) if CALLBACK_DSL.include?(node.name.to_s)
+        super
+      end
+
+      private
+
+      def collect(node)
+        symbol_arguments(node).each do |sym|
+          @referenced_names << sym
+          qualifier = @namespace.join("::")
+          @referenced_names << "#{qualifier}##{sym}" unless qualifier.empty?
+        end
+      end
+
+      def symbol_arguments(node)
+        args = node.arguments&.arguments || []
+        args.filter_map do |arg|
+          arg.unescaped if arg.is_a?(Prism::SymbolNode)
+        end
+      end
+    end
+  end
+end

data/lib/moult/version.rb

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

data/lib/moult.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "moult/version"
+
+# Moult provides confidence-graded codebase intelligence for Ruby.
+#
+# Phase 1 exposes a single capability: ranking files by a complexity x churn
+# hotspot score. See {Moult::CLI} for the command-line entrypoint.
+module Moult
+  class Error < StandardError; end
+
+  autoload :CLI, "moult/cli"
+  autoload :Parser, "moult/parser"
+  autoload :MethodDef, "moult/parser"
+  autoload :ABC, "moult/abc"
+  autoload :Churn, "moult/churn"
+  autoload :Git, "moult/git"
+  autoload :Scoring, "moult/scoring"
+  autoload :Discovery, "moult/discovery"
+  autoload :Report, "moult/report"
+  autoload :Span, "moult/span"
+  autoload :SymbolId, "moult/symbol_id"
+
+  # Phase 2: confidence-graded dead-code analysis.
+  autoload :Index, "moult/index"
+  autoload :Confidence, "moult/confidence"
+  autoload :DeadCode, "moult/dead_code"
+  autoload :DeadCodeReport, "moult/dead_code_report"
+  autoload :RailsConventions, "moult/rails_conventions"
+  autoload :SymbolScanner, "moult/symbol_scanner"
+
+  # Phase 3: runtime coverage layer (static<->runtime merge).
+  autoload :Coverage, "moult/coverage"
+  autoload :CoverageReport, "moult/coverage_report"
+
+  # Static slice: flay-backed structural duplication detection.
+  autoload :Clones, "moult/clones"
+  autoload :Duplication, "moult/duplication"
+  autoload :DuplicationReport, "moult/duplication_report"
+
+  # Health slice: a composite health score aggregating the other analyses.
+  autoload :Health, "moult/health"
+  autoload :HealthReport, "moult/health_report"
+
+  # Static slice: packwerk-backed architecture-boundary violations.
+  autoload :Boundaries, "moult/boundaries"
+  autoload :BoundariesReport, "moult/boundaries_report"
+
+  # Static slice: OpenFeature feature-flag usage (provider-agnostic).
+  autoload :FlagScanner, "moult/flag_scanner"
+  autoload :Flags, "moult/flags"
+  autoload :FlagsReport, "moult/flags_report"
+
+  # Phase 4 (core): the diff-aware PR risk gate — the first/only verdict layer.
+  autoload :Diff, "moult/diff"
+  autoload :Gate, "moult/gate"
+  autoload :GateReport, "moult/gate_report"
+
+  # Cloud upload: sanitising projection for the moult-action GitHub Action.
+  autoload :CloudUpload, "moult/cloud_upload"
+
+  module Formatters
+    autoload :TextTable, "moult/formatters/text_table"
+    autoload :Table, "moult/formatters/table"
+    autoload :Json, "moult/formatters/json"
+    autoload :DeadCodeTable, "moult/formatters/dead_code_table"
+    autoload :DeadCodeJson, "moult/formatters/dead_code_json"
+    autoload :CoverageTable, "moult/formatters/coverage_table"
+    autoload :CoverageJson, "moult/formatters/coverage_json"
+    autoload :DuplicationTable, "moult/formatters/duplication_table"
+    autoload :DuplicationJson, "moult/formatters/duplication_json"
+    autoload :HealthTable, "moult/formatters/health_table"
+    autoload :HealthJson, "moult/formatters/health_json"
+    autoload :BoundariesTable, "moult/formatters/boundaries_table"
+    autoload :BoundariesJson, "moult/formatters/boundaries_json"
+    autoload :FlagsTable, "moult/formatters/flags_table"
+    autoload :FlagsJson, "moult/formatters/flags_json"
+    autoload :GateMessage, "moult/formatters/gate_message"
+    autoload :GateTable, "moult/formatters/gate_table"
+    autoload :GateJson, "moult/formatters/gate_json"
+    autoload :GateGithub, "moult/formatters/gate_github"
+    autoload :GateSarif, "moult/formatters/gate_sarif"
+  end
+end

data/schema/boundaries.schema.json

@@ -0,0 +1,125 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/boundaries.schema.json",
+  "title": "Moult architecture-boundaries report",
+  "description": "Typed output contract for `moult boundaries`. One of Moult's two protected APIs. Each finding is a recorded packwerk boundary violation, classified by severity. A violation is a recorded fact (packwerk resolved the constant via Zeitwerk and verified it crosses a declared boundary), so confidence is null and severity carries the signal; nothing here asserts the code is certainly wrong.",
+  "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", "detector"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "detector": {
+          "type": "object",
+          "required": ["backend", "backend_version", "configured"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"description": "Boundary backend, e.g. \"packwerk\".", "type": "string"},
+            "backend_version": {"type": ["string", "null"]},
+            "configured": {"description": "Whether the project is packwerk-configured (a packwerk.yml exists). When false, findings is empty.", "type": "boolean"}
+          }
+        }
+      }
+    },
+    "summary": {
+      "type": "object",
+      "required": ["findings", "violations", "by_type", "by_severity"],
+      "additionalProperties": false,
+      "properties": {
+        "findings": {"description": "Number of violation groups.", "type": "integer", "minimum": 0},
+        "violations": {"description": "Total referencing sites across all groups.", "type": "integer", "minimum": 0},
+        "by_type": {"description": "Violation count keyed by violation type.", "type": "object", "additionalProperties": {"type": "integer", "minimum": 0}},
+        "by_severity": {"description": "Violation count keyed by severity.", "type": "object", "additionalProperties": {"type": "integer", "minimum": 0}}
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/finding"}
+    }
+  },
+  "$defs": {
+    "reason": {
+      "description": "One auditable note behind a finding's severity classification.",
+      "type": "object",
+      "required": ["rule", "detail"],
+      "additionalProperties": false,
+      "properties": {
+        "rule": {"type": "string"},
+        "detail": {"type": "string"}
+      }
+    },
+    "occurrence": {
+      "description": "One referencing site of a violation group.",
+      "type": "object",
+      "required": ["symbol_id", "path"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol_id": {
+          "description": "Method-level join key (\"<path>:<start_line>:<fqname>\"), shared with the other contracts. Null in this slice: packwerk's recorded violations are file-keyed (no line numbers), so no enclosing method is resolved. Findings join at path granularity. Kept nullable for forward-compatibility with line-level offenses.",
+          "type": ["string", "null"]
+        },
+        "path": {"description": "Root-relative referencing file path; the health files[] join key.", "type": "string"}
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["category", "confidence", "violation_type", "severity", "referencing_package", "defining_package", "constant", "reasons", "occurrences"],
+      "additionalProperties": false,
+      "properties": {
+        "category": {
+          "description": "Always \"architecture_boundary\" in this contract.",
+          "type": "string",
+          "const": "architecture_boundary"
+        },
+        "confidence": {
+          "description": "Always null here: a packwerk violation is a recorded fact, not a probabilistic candidate. The per-finding signal is carried by `severity`, never by a manufactured confidence.",
+          "$ref": "common.schema.json#/$defs/confidence"
+        },
+        "violation_type": {
+          "description": "The packwerk violation kind.",
+          "type": "string",
+          "enum": ["dependency", "privacy", "visibility", "folder_privacy", "layer"]
+        },
+        "severity": {
+          "description": "How architecturally significant the violation kind is. A classification of the recorded fact, never an assertion the code is wrong.",
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        },
+        "referencing_package": {"description": "The package making the boundary-crossing reference (\".\" for the root package).", "type": "string"},
+        "defining_package": {"description": "The package that owns the referenced constant.", "type": "string"},
+        "constant": {"description": "The constant that crosses the boundary.", "type": "string"},
+        "reasons": {
+          "description": "The notes behind the severity classification.",
+          "type": "array",
+          "items": {"$ref": "#/$defs/reason"}
+        },
+        "occurrences": {
+          "description": "The referencing sites of this violation group; at least one.",
+          "type": "array",
+          "minItems": 1,
+          "items": {"$ref": "#/$defs/occurrence"}
+        }
+      }
+    }
+  }
+}

data/schema/common.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/common.schema.json",
+  "title": "Moult shared definitions",
+  "description": "Definitions shared across Moult's protected output contracts (hotspots, deadcode) so the confidence model and source spans cannot drift between them.",
+  "$defs": {
+    "unit_interval": {
+      "description": "A confidence in [0, 1]. Findings are confidence-graded, never asserted as certain death.",
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1
+    },
+    "confidence": {
+      "description": "Reserved nullable confidence slot. Null where an analysis does not (yet) assert a confidence; otherwise a value in [0, 1].",
+      "oneOf": [
+        {"type": "null"},
+        {"$ref": "#/$defs/unit_interval"}
+      ]
+    },
+    "category": {
+      "description": "Finding classification (e.g. \"dead_code\"). Null where unclassified.",
+      "type": ["string", "null"]
+    },
+    "span": {
+      "description": "Definition source range. Lines 1-based, columns 0-based (Prism offsets).",
+      "type": "object",
+      "required": ["start_line", "start_column", "end_line", "end_column"],
+      "additionalProperties": false,
+      "properties": {
+        "start_line": {"type": "integer", "minimum": 1},
+        "start_column": {"type": "integer", "minimum": 0},
+        "end_line": {"type": "integer", "minimum": 1},
+        "end_column": {"type": "integer", "minimum": 0}
+      }
+    },
+    "runtime": {
+      "description": "Runtime coverage classification for a symbol. hot=an executable body line ran; cold=tracked file, no body line ran; untracked=no signal (file absent from the dataset, a constant, or unclassifiable). Null where no coverage was merged. Evidence, never an assertion of certain death.",
+      "oneOf": [
+        {"type": "null"},
+        {"type": "string", "enum": ["hot", "cold", "untracked"]}
+      ]
+    },
+    "coverage_source": {
+      "description": "Provenance of merged runtime coverage. Null where no coverage was merged.",
+      "oneOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "required": ["backend", "version", "collected_at"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"description": "Coverage backend, e.g. \"simplecov\" or \"coverage\".", "type": "string"},
+            "version": {"type": ["string", "null"]},
+            "collected_at": {"type": ["string", "null"], "format": "date-time"}
+          }
+        }
+      ]
+    },
+    "provider_source": {
+      "description": "Provenance of a merged feature-flag provider snapshot (--provider). Null where no snapshot was merged. The flags analogue of coverage_source: evidence about which keys the provider knows, never a claim a flag is certainly stale.",
+      "oneOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "required": ["backend", "version", "exported_at"],
+          "additionalProperties": false,
+          "properties": {
+            "backend": {"description": "Provider snapshot backend, e.g. \"flagd\".", "type": "string"},
+            "version": {"type": ["string", "null"]},
+            "exported_at": {"type": ["string", "null"], "format": "date-time"}
+          }
+        }
+      ]
+    }
+  }
+}

data/schema/coverage.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/moult-rb/moult-rb/blob/main/schema/coverage.schema.json",
+  "title": "Moult runtime coverage map",
+  "description": "Typed output contract for `moult coverage`: a per-symbol hot/cold/untracked map produced by resolving line-keyed coverage to definition spans. A diagnostic view of the same runtime evidence `moult deadcode --coverage` merges into confidence; it makes no dead-code claim.",
+  "type": "object",
+  "required": ["schema_version", "tool", "analysis", "summary", "symbols"],
+  "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", "coverage", "index"],
+      "additionalProperties": false,
+      "properties": {
+        "root": {"type": "string"},
+        "git_ref": {"type": ["string", "null"]},
+        "generated_at": {"type": ["string", "null"], "format": "date-time"},
+        "coverage": {"$ref": "common.schema.json#/$defs/coverage_source"},
+        "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": {
+      "description": "Counts of symbols by runtime classification.",
+      "type": "object",
+      "required": ["hot", "cold", "untracked"],
+      "additionalProperties": false,
+      "properties": {
+        "hot": {"type": "integer", "minimum": 0},
+        "cold": {"type": "integer", "minimum": 0},
+        "untracked": {"type": "integer", "minimum": 0}
+      }
+    },
+    "symbols": {
+      "type": "array",
+      "items": {"$ref": "#/$defs/symbol"}
+    }
+  },
+  "$defs": {
+    "symbol": {
+      "type": "object",
+      "required": ["symbol_id", "kind", "name", "span", "runtime"],
+      "additionalProperties": false,
+      "properties": {
+        "symbol_id": {
+          "description": "Stable join key shared with the hotspots and deadcode contracts: \"<path>:<start_line>:<fqname>\".",
+          "type": "string"
+        },
+        "kind": {"type": "string", "enum": ["method", "constant"]},
+        "name": {"type": "string"},
+        "span": {"$ref": "common.schema.json#/$defs/span"},
+        "runtime": {
+          "description": "hot/cold/untracked. Never null here: `moult coverage` always merges a dataset.",
+          "type": "string",
+          "enum": ["hot", "cold", "untracked"]
+        }
+      }
+    }
+  }
+}