moult 0.1.0

data/lib/moult/formatters/duplication_table.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable table of duplication candidates. Renders from the same
+    # {DuplicationReport} as the JSON formatter so the two cannot disagree.
+    # Sorting already happened in {Duplication}; this layer owns column
+    # formatting only.
+    #
+    # The heading is deliberate: these are confidence-graded candidates, never
+    # certainties.
+    module DuplicationTable
+      MAX_LOCATIONS = 3
+      RIGHT_ALIGNED = [0, 2, 4].freeze # CONF, MASS, COUNT
+
+      module_function
+
+      # @param report [DuplicationReport]
+      # @return [String]
+      def render(report)
+        findings = report.findings
+        return "No duplication found." if findings.empty?
+
+        headers = %w[CONF KIND MASS NODE COUNT LOCATIONS]
+        rows = findings.map { |f| row(f) }
+        [heading(findings.size), "", TextTable.render(headers, rows, right_aligned: RIGHT_ALIGNED)].join("\n")
+      end
+
+      def heading(count)
+        "Duplication candidates (confidence-graded — not certainties): #{count} clone sets"
+      end
+
+      def row(finding)
+        [
+          conf(finding.confidence),
+          finding.kind.to_s,
+          finding.mass.to_s,
+          finding.node_type,
+          finding.occurrences.size.to_s,
+          locations(finding.occurrences)
+        ]
+      end
+
+      def locations(occurrences)
+        shown = occurrences.first(MAX_LOCATIONS).map { |o| "#{o.path}:#{o.line}" }
+        extra = occurrences.size - shown.size
+        extra.positive? ? "#{shown.join(", ")} (+#{extra} more)" : shown.join(", ")
+      end
+
+      def conf(value)
+        format("%.2f", value)
+      end
+    end
+  end
+end

data/lib/moult/formatters/flags_json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # JSON rendering of a {FlagsReport}. A thin pass-through of the report's own
+    # +to_h+ so the serialized shape cannot drift from the table formatter or the
+    # contract.
+    module FlagsJson
+      module_function
+
+      # @param report [FlagsReport]
+      # @return [String]
+      def render(report)
+        JSON.pretty_generate(report.to_h)
+      end
+    end
+  end
+end

data/lib/moult/formatters/flags_table.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable table of OpenFeature flag references. Renders from the same
+    # {FlagsReport} as the JSON formatter so the two cannot disagree. Sorting already
+    # happened in {Flags}; this layer owns column formatting only.
+    #
+    # The heading is deliberate. Without a provider snapshot these are flag *usage*
+    # facts (staleness needs a provider). With one, they are confidence-graded
+    # staleness *candidates* — never certainties; the STATUS/CONF columns and the
+    # heading say so.
+    module FlagsTable
+      MAX_LOCATIONS = 3
+      NO_DEFAULTS = "-"
+      NO_STALENESS = "-"
+      RIGHT_ALIGNED = [2].freeze # REFS (usage view)
+      RIGHT_ALIGNED_GRADED = [3, 4].freeze # CONF, REFS (staleness view)
+
+      module_function
+
+      # @param report [FlagsReport]
+      # @return [String]
+      def render(report)
+        findings = report.findings
+        return "No OpenFeature flag references found." if findings.empty?
+
+        graded = !report.provider_source.nil?
+        headers = graded ? %w[KEY TYPE STATUS CONF REFS DEFAULTS LOCATIONS] : %w[KEY TYPE REFS DEFAULTS LOCATIONS]
+        right = graded ? RIGHT_ALIGNED_GRADED : RIGHT_ALIGNED
+        rows = findings.map { |f| row(f, graded) }
+        [heading(report.summary, graded), "", TextTable.render(headers, rows, right_aligned: right)].join("\n")
+      end
+
+      def heading(summary, graded)
+        dynamic = summary[:dynamic_references]
+        tail = dynamic.positive? ? ", #{dynamic} dynamic (uncatalogued)" : ""
+        lead = if graded
+          "OpenFeature flag staleness candidates (confidence-graded, never certain): "
+        else
+          "OpenFeature flag references (usage facts, not staleness — that needs a live provider): "
+        end
+        "#{lead}#{summary[:flags]} flags, #{summary[:references]} references#{tail}"
+      end
+
+      def row(finding, graded)
+        cells = [finding.flag_key, finding.value_type]
+        cells.push(status(finding), confidence(finding)) if graded
+        cells.push(
+          finding.reference_count.to_s,
+          defaults(finding.default_values),
+          locations(finding.occurrences)
+        )
+        cells
+      end
+
+      def status(finding)
+        finding.staleness&.status || NO_STALENESS
+      end
+
+      def confidence(finding)
+        finding.staleness ? format("%.2f", finding.staleness.confidence) : NO_STALENESS
+      end
+
+      def defaults(values)
+        values.empty? ? NO_DEFAULTS : values.join(", ")
+      end
+
+      def locations(occurrences)
+        shown = occurrences.first(MAX_LOCATIONS).map { |o| "#{o.path}:#{o.line}" }
+        extra = occurrences.size - shown.size
+        extra.positive? ? "#{shown.join(", ")} (+#{extra} more)" : shown.join(", ")
+      end
+    end
+  end
+end

data/lib/moult/formatters/gate_github.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Moult
+  # CI projections of the gate verdict. These render the SAME contributing
+  # findings the JSON contract carries into machine formats a code-review tool can
+  # consume — but they only EMIT text (annotations / a SARIF document). Posting to
+  # any GitHub API is the App's job (Phase 4), explicitly out of scope here.
+  module Formatters
+    # GitHub Actions workflow-command annotations: one `::error` line per
+    # contributing finding, so a PR shows the gate's findings inline when run in
+    # Actions. Format and escaping follow the GitHub Actions workflow-commands
+    # spec. A passing gate emits a single `::notice`.
+    module GateGithub
+      module_function
+
+      # @param report [GateReport]
+      # @return [String]
+      def render(report)
+        failed = report.rules.select { |r| r.evaluated && r.passed == false }
+        return pass_notice(report) if failed.empty?
+
+        failed.flat_map { |rule| rule.findings.map { |f| annotation(rule, f) } }.join("\n")
+      end
+
+      def pass_notice(report)
+        "::notice title=#{escape_prop("Moult gate")}::#{escape_data("gate passed (#{report.summary[:evaluated]} rules evaluated)")}"
+      end
+
+      def annotation(rule, finding)
+        props = {file: finding.path}
+        props[:line] = finding.line if finding.line
+        props[:title] = "Moult gate: #{rule.rule}"
+        prop_str = props.map { |k, v| "#{k}=#{escape_prop(v.to_s)}" }.join(",")
+        "::error #{prop_str}::#{escape_data(message(rule, finding))}"
+      end
+
+      def message(rule, finding)
+        GateMessage.for(rule, finding)
+      end
+
+      # Per the workflow-command spec: escape % CR LF in message data; additionally
+      # escape : and , in property values.
+      def escape_data(value)
+        value.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+      end
+
+      def escape_prop(value)
+        escape_data(value).gsub(":", "%3A").gsub(",", "%2C")
+      end
+    end
+  end
+end

data/lib/moult/formatters/gate_json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # The gate's machine contract: a thin pass-through over {GateReport#to_h},
+    # validated against schema/gate.schema.json. Renders from the same report as
+    # every other gate formatter so they cannot drift.
+    module GateJson
+      module_function
+
+      # @param report [GateReport]
+      # @return [String]
+      def render(report)
+        JSON.pretty_generate(report.to_h)
+      end
+    end
+  end
+end

data/lib/moult/formatters/gate_message.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # The one-line description of a gate finding, shared by the GitHub-annotation
+    # and SARIF projections so the two render identical text. Stays humble: it
+    # reports the observed signal against the threshold, never a claim of certainty.
+    module GateMessage
+      module_function
+
+      # @param rule [Gate::Evaluation::RuleOutcome]
+      # @param finding [Gate::Evaluation::Contribution]
+      # @return [String]
+      def for(rule, finding)
+        "#{finding.category} #{finding.value} on changed code violates #{rule.rule} (threshold #{rule.threshold})"
+      end
+    end
+  end
+end

data/lib/moult/formatters/gate_sarif.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # SARIF 2.1.0 projection of the gate verdict — the static-analysis interchange
+    # format GitHub code scanning and reviewdog consume. One `rule` per policy
+    # rule; one `result` (level "error") per contributing finding behind a failed
+    # rule. Emits the document only; uploading it is the consumer's job.
+    #
+    # A finding's `value` is a graded/classified signal (confidence/ABC/mass/
+    # severity), so the result text reports it as such — never as a certainty.
+    module GateSarif
+      SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+      INFORMATION_URI = "https://github.com/moult-rb/moult-rb"
+
+      module_function
+
+      # @param report [GateReport]
+      # @return [String]
+      def render(report)
+        JSON.pretty_generate(document(report))
+      end
+
+      def document(report)
+        {
+          "$schema" => SARIF_SCHEMA,
+          "version" => "2.1.0",
+          "runs" => [{
+            "tool" => {
+              "driver" => {
+                "name" => "moult",
+                "version" => Moult::VERSION,
+                "informationUri" => INFORMATION_URI,
+                "rules" => report.rules.map { |r| rule_descriptor(r) }
+              }
+            },
+            "results" => results(report)
+          }]
+        }
+      end
+
+      def rule_descriptor(rule)
+        {
+          "id" => rule.rule,
+          "shortDescription" => {"text" => rule.rule.tr("_", " ")},
+          "properties" => {"threshold" => rule.threshold.to_s, "evaluated" => rule.evaluated}
+        }
+      end
+
+      def results(report)
+        report.rules.select { |r| r.evaluated && r.passed == false }.flat_map do |rule|
+          rule.findings.map { |f| result(rule, f) }
+        end
+      end
+
+      def result(rule, finding)
+        {
+          "ruleId" => rule.rule,
+          "level" => "error",
+          "message" => {"text" => message(rule, finding)},
+          "locations" => [{"physicalLocation" => physical_location(finding)}]
+        }
+      end
+
+      def physical_location(finding)
+        location = {"artifactLocation" => {"uri" => finding.path}}
+        location["region"] = {"startLine" => finding.line} if finding.line
+        location
+      end
+
+      def message(rule, finding)
+        GateMessage.for(rule, finding)
+      end
+    end
+  end
+end

data/lib/moult/formatters/gate_table.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable gate result: a PASS/FAIL banner, the scope it ran over, a
+    # per-rule table (with each rule's observed value vs threshold), and the
+    # contributing findings behind any failure. Renders from the same {GateReport}
+    # as the JSON/CI formatters so they cannot disagree.
+    #
+    # The verdict is an auditable application of the recorded policy — the heading
+    # says so; nothing here claims the code is certainly wrong.
+    module GateTable
+      module_function
+
+      # @param report [GateReport]
+      # @return [String]
+      def render(report)
+        [banner(report), "", rule_table(report), contributions(report)]
+          .reject(&:empty?).join("\n")
+      end
+
+      def banner(report)
+        verdict = report.verdict.upcase
+        "moult gate: #{verdict}  (#{scope_label(report)})"
+      end
+
+      def scope_label(report)
+        if report.scope == :all || report.scope == "all"
+          "scope: all (whole codebase)"
+        else
+          base = report.base_ref || "base"
+          mb = report.merge_base ? " @ #{report.merge_base[0, 7]}" : ""
+          "scope: diff vs #{base}#{mb}"
+        end
+      end
+
+      def rule_table(report)
+        headers = %w[RULE OBSERVED THRESHOLD RESULT]
+        rows = report.rules.map do |rule|
+          [rule.rule, observed(rule), rule.threshold.to_s, result(rule)]
+        end
+        TextTable.render(headers, rows)
+      end
+
+      def observed(rule)
+        return "-" if rule.observed.nil?
+
+        rule.observed.to_s
+      end
+
+      def result(rule)
+        return "skipped" unless rule.evaluated
+
+        rule.passed ? "pass" : "FAIL"
+      end
+
+      def contributions(report)
+        failed = report.rules.select { |r| r.evaluated && r.passed == false }
+        return "" if failed.empty?
+
+        lines = failed.flat_map { |rule| rule.findings.map { |f| contribution_line(rule, f) } }
+        ["", "Contributing findings:", *lines].join("\n")
+      end
+
+      def contribution_line(rule, finding)
+        loc = finding.line ? "#{finding.path}:#{finding.line}" : finding.path
+        "  [#{rule.rule}] #{loc}  #{finding.category} (#{finding.value})"
+      end
+    end
+  end
+end

data/lib/moult/formatters/health_json.rb

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

data/lib/moult/formatters/health_table.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable health summary: a headline composite, the per-component
+    # breakdown (including the skipped/errored ones), and the least-healthy files.
+    # Renders from the same {HealthReport} as the JSON formatter so the two cannot
+    # disagree; ordering already happened in {Health}.
+    #
+    # The heading is deliberate: this is a graded signal, never a verdict.
+    module HealthTable
+      DEFAULT_FILE_LIMIT = 20
+      DASH = "—"
+
+      module_function
+
+      # @param report [HealthReport]
+      # @param file_limit [Integer, nil] how many worst files to show (nil = all)
+      # @return [String]
+      def render(report, file_limit: DEFAULT_FILE_LIMIT)
+        [heading(report), "", components_section(report), "", files_section(report, file_limit)]
+          .join("\n").rstrip
+      end
+
+      def heading(report)
+        if report.score.nil?
+          "Codebase health: n/a — no analysis produced a signal"
+        else
+          present = report.components.count(&:present)
+          total = report.components.size
+          "Codebase health: #{report.grade} (#{format("%.2f", report.score)}) " \
+            "— a graded signal, not a verdict  [#{present}/#{total} components]"
+        end
+      end
+
+      def components_section(report)
+        headers = %w[COMPONENT SCORE WEIGHT NOTE]
+        rows = report.components.map { |c| component_row(c) }
+        right = [1, 2] # SCORE, WEIGHT
+        ["Components:", TextTable.render(headers, rows, right_aligned: right)].join("\n")
+      end
+
+      def component_row(component)
+        [
+          component.name,
+          component.present ? format("%.2f", component.score) : DASH,
+          format("%.2f", component.weight),
+          component_note(component)
+        ]
+      end
+
+      def component_note(component)
+        return component.diagnostic.to_s unless component.present
+        component.reasons.first&.detail.to_s
+      end
+
+      def files_section(report, file_limit)
+        files = report.files
+        return "Files: none with a health signal." if files.empty?
+
+        shown = file_limit ? files.first(file_limit) : files
+        headers = %w[SCORE GRADE FILE COMPONENTS]
+        rows = shown.map { |f| file_row(f) }
+        extra = files.size - shown.size
+        suffix = extra.positive? ? " (top #{shown.size} of #{files.size})" : ""
+        title = "Least-healthy files#{suffix}:"
+        [title, TextTable.render(headers, rows, right_aligned: [0])].join("\n")
+      end
+
+      def file_row(file)
+        [
+          format("%.2f", file.score),
+          file.grade,
+          file.path,
+          file.components.keys.join(",")
+        ]
+      end
+    end
+  end
+end

data/lib/moult/formatters/json.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # Emits the typed JSON output contract (schema/hotspots.schema.json). Renders
+    # straight from {Report#to_h}; only presentation concerns (limiting) live
+    # here, so the serialized shape can never drift from the result model.
+    module Json
+      module_function
+
+      # @param report [Report]
+      # @param limit [Integer, nil] keep only the top N hotspots
+      # @return [String] pretty-printed JSON
+      def render(report, limit: nil)
+        data = report.to_h
+        data[:hotspots] = data[:hotspots].first(limit) if limit
+        JSON.pretty_generate(data)
+      end
+    end
+  end
+end

data/lib/moult/formatters/table.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable ranked table. Renders from the same {Report} as the JSON
+    # formatter, so the two cannot disagree. Sorting already happened in
+    # {Scoring}; this layer owns limiting and column formatting only.
+    module Table
+      HEADERS = ["#", "SCORE", "COMPLEXITY", "CHURN", "FILE", "WORST METHOD"].freeze
+      # Right-align the numeric columns; left-align file and method.
+      RIGHT_ALIGNED = [0, 1, 2, 3].freeze
+      GUTTER = "  "
+
+      module_function
+
+      # @param report [Report]
+      # @param limit [Integer, nil] show only the top N hotspots
+      # @return [String]
+      def render(report, limit: nil)
+        hotspots = report.hotspots
+        hotspots = hotspots.first(limit) if limit
+        return "No hotspots found." if hotspots.empty?
+
+        rows = hotspots.each_with_index.map { |h, i| row(h, i + 1) }
+        [heading(report, hotspots.size), "", table(rows)].join("\n")
+      end
+
+      def heading(report, shown)
+        total = report.hotspots.size
+        scope = (shown < total) ? "top #{shown} of #{total}" : total.to_s
+        window = report.churn_window ? " — churn over #{report.churn_window}" : ""
+        "Hotspots (complexity x churn): #{scope} files#{window}"
+      end
+
+      def row(hotspot, rank)
+        worst = hotspot.worst_method
+        worst_cell = worst ? "#{worst.name} (#{num(worst.abc)})" : "-"
+        [
+          rank.to_s,
+          num(hotspot.score),
+          num(hotspot.complexity),
+          hotspot.churn.to_s,
+          hotspot.path,
+          worst_cell
+        ]
+      end
+
+      def table(rows)
+        widths = column_widths(rows)
+        ([HEADERS] + rows).map { |cells| format_row(cells, widths) }.join("\n")
+      end
+
+      def column_widths(rows)
+        HEADERS.each_index.map do |col|
+          ([HEADERS[col]] + rows.map { |r| r[col] }).map(&:length).max
+        end
+      end
+
+      def format_row(cells, widths)
+        cells.each_with_index.map { |cell, col|
+          RIGHT_ALIGNED.include?(col) ? cell.rjust(widths[col]) : cell.ljust(widths[col])
+        }.join(GUTTER).rstrip
+      end
+
+      def num(value)
+        format("%.1f", value)
+      end
+    end
+  end
+end

data/lib/moult/formatters/text_table.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Shared plumbing for the header + rows text tables every analysis formatter
+    # renders. Extracted so the column-width/alignment logic lives in exactly one
+    # place instead of being copied into each `*_table` formatter (the gate caught
+    # that duplication when run on Moult itself).
+    #
+    # Columns left-align by default; pass the 0-based indices to right-align (e.g.
+    # numeric columns) in +right_aligned+.
+    module TextTable
+      GUTTER = "  "
+
+      module_function
+
+      # @param headers [Array<String>]
+      # @param rows [Array<Array<String>>]
+      # @param right_aligned [Array<Integer>] 0-based column indices to right-align
+      # @return [String] the header row followed by each data row, newline-joined
+      def render(headers, rows, right_aligned: [])
+        widths = column_widths(headers, rows)
+        ([headers] + rows).map { |cells| format_row(cells, widths, right_aligned) }.join("\n")
+      end
+
+      def column_widths(headers, rows)
+        headers.each_index.map do |col|
+          ([headers[col]] + rows.map { |r| r[col] }).map(&:length).max
+        end
+      end
+
+      def format_row(cells, widths, right_aligned)
+        cells.each_with_index.map { |cell, col|
+          right_aligned.include?(col) ? cell.rjust(widths[col]) : cell.ljust(widths[col])
+        }.join(GUTTER).rstrip
+      end
+    end
+  end
+end

data/lib/moult/gate/config.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Moult
+  module Gate
+    # Loads gate policy overrides from a project config file (.moult.yml by
+    # default) and hands them to {Policy}. Config is plain YAML — psych is stdlib,
+    # so the gate adds no new runtime dependency. Only the `gate:` section is read;
+    # everything else is ignored, leaving room for future Moult config.
+    #
+    # IO lives here, never in the pure {Policy}/{Evaluation} models: this resolves
+    # a path and reads a file, then defers entirely to {Policy.load}.
+    module Config
+      DEFAULT_FILENAME = ".moult.yml"
+
+      module_function
+
+      # @param root [String] absolute analysis root
+      # @param config_path [String, nil] explicit --config path; nil auto-detects
+      #   .moult.yml at the root
+      # @return [Policy] defaults when no config is present
+      # @raise [Moult::Error] when an explicit path is missing or the file is unreadable
+      def policy_for(root:, config_path: nil)
+        path = resolve(root, config_path)
+        return Policy.default unless path
+
+        data = YAML.safe_load_file(path) || {}
+        unless data.is_a?(Hash)
+          raise Moult::Error, "config #{relative(path, root)} must be a YAML mapping"
+        end
+
+        overrides = data["gate"] || data[:gate] || {}
+        Policy.load(overrides, source: relative(path, root))
+      rescue Psych::SyntaxError => e
+        raise Moult::Error, "could not parse config #{relative(path, root)}: #{e.message}"
+      end
+
+      def resolve(root, config_path)
+        if config_path
+          return config_path if File.file?(config_path)
+
+          raise Moult::Error, "no such config file: #{config_path}"
+        end
+
+        default = File.join(root, DEFAULT_FILENAME)
+        File.file?(default) ? default : nil
+      end
+
+      def relative(path, root)
+        SymbolId.relative_path(File.expand_path(path), root)
+      end
+    end
+  end
+end