moult 0.1.0

data/lib/moult/flags/staleness.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+module Moult
+  module Flags
+    # The confidence-graded per-finding model for feature-flag STALENESS — this
+    # slice's first real use of Moult's protected per-finding confidence API. Where
+    # {Classification} grades recorded USAGE (a reference is a fact, so its confidence
+    # is null), staleness is a genuine judgement: given a flag's observed references
+    # and the state the provider snapshot reports for its key, how strong a candidate
+    # is it for removal?
+    #
+    # Like the static<->runtime coverage merge (see {Coverage::Resolver}), the
+    # snapshot is EVIDENCE, not proof. A flag is never asserted certainly stale or
+    # dead. The provider state (archived / disabled / fully rolled out) and the
+    # join result (absent — referenced in code, unknown to the provider) raise
+    # confidence; dynamic, non-literal keys in the codebase LOWER it, because the
+    # snapshot may be partial or the key resolved dynamically.
+    #
+    # {classify} is a pure function of the joined facts — no IO, no Prism, no clock —
+    # so it is pinned against hand-built inputs exactly like {ABC}, the coverage
+    # {Resolver}, the duplication {Confidence} model, {Boundaries::Severity}, and
+    # {Classification}. The statuses and confidence knees are deliberate v1
+    # heuristics; drift is a bug.
+    #
+    # Time-based "stale-since" decay (a flag untouched for N days) is deferred: it
+    # needs a +now+ clock and a threshold knee, so it would make this model impure.
+    # The snapshot's +exported_at+ and a flag's +updated_at+ are captured as evidence
+    # to seed it later, exactly as coverage captured +collected_at+ while deferring
+    # stale-detection.
+    module Staleness
+      # The provider explicitly retired the flag. The strongest removal candidate.
+      ARCHIVED = "archived"
+      # Referenced in code, but the snapshot has no such key (deleted/renamed in the
+      # provider, or managed elsewhere). Strong, but humbled by dynamic references.
+      ABSENT = "absent"
+      # Disabled in the provider (served to no one): the enabled branch is unreachable.
+      DISABLED = "disabled"
+      # Fully rolled out (enabled, no targeting — one variant served to all): the
+      # other branch is never taken.
+      ROLLED_OUT = "rolled_out"
+      # Enabled with targeting (serving multiple variations): actively evaluated,
+      # NOT a removal candidate.
+      ACTIVE = "active"
+
+      STATUSES = [ARCHIVED, ABSENT, DISABLED, ROLLED_OUT, ACTIVE].freeze
+
+      # Pinned confidence knees per status (removal-candidate strength).
+      ARCHIVED_CONFIDENCE = 0.9
+      ABSENT_CONFIDENCE = 0.7
+      ROLLED_OUT_CONFIDENCE = 0.6
+      DISABLED_CONFIDENCE = 0.5
+      ACTIVE_CONFIDENCE = 0.0
+
+      # Humility modifier: subtracted from an +absent+ candidate when the codebase
+      # has dynamic (non-literal-key) flag references — the key the static scan could
+      # not resolve may BE this one, so the snapshot's silence is less trustworthy.
+      DYNAMIC_REFERENCE_PENALTY = 0.2
+
+      # One auditable note behind a staleness judgement. Local to the flags slice
+      # (like {Classification::Reason}); categorical, so no +delta+.
+      Reason = Struct.new(:rule, :detail) do
+        def to_h
+          {rule: rule.to_s, detail: detail}
+        end
+      end
+
+      # The graded result: the staleness status, its confidence in [0, 1], and the
+      # reasons behind them.
+      Assessment = Struct.new(:status, :confidence, :reasons) do
+        def to_h
+          {status: status, confidence: confidence, reasons: reasons.map(&:to_h)}
+        end
+      end
+
+      module_function
+
+      # @param state [Snapshot::FlagState, nil] the provider's state for this key, or
+      #   nil when the snapshot does not know the key (an +absent+ candidate)
+      # @param has_dynamic_references [Boolean] whether the codebase has any dynamic
+      #   (non-literal-key) flag references (a snapshot-completeness caveat)
+      # @return [Assessment]
+      def classify(state:, has_dynamic_references: false)
+        return absent(has_dynamic_references) if state.nil?
+        return archived(state) if state.archived
+        return disabled(state) if state.enabled == false
+        return rolled_out(state) if state.enabled && !state.has_targeting
+        active(state)
+      end
+
+      def absent(has_dynamic_references)
+        reasons = [Reason.new(rule: :absent_from_provider,
+          detail: "referenced in code but unknown to the provider snapshot (deleted or renamed in the provider); a candidate for removal")]
+        confidence = ABSENT_CONFIDENCE
+        if has_dynamic_references
+          confidence -= DYNAMIC_REFERENCE_PENALTY
+          reasons << Reason.new(rule: :dynamic_references,
+            detail: "the codebase has dynamic (non-literal) flag keys, so the snapshot may be incomplete; confidence lowered")
+        end
+        assess(ABSENT, confidence, reasons)
+      end
+
+      def archived(state)
+        reasons = [Reason.new(rule: :provider_archived,
+          detail: "the provider marks this flag archived/retired; a strong candidate for removal")]
+        reasons << updated_at_reason(state)
+        assess(ARCHIVED, ARCHIVED_CONFIDENCE, reasons.compact)
+      end
+
+      def disabled(state)
+        reasons = [Reason.new(rule: :provider_disabled,
+          detail: "disabled in the provider (served to no one); the enabled branch is unreachable — a candidate for removal")]
+        reasons << updated_at_reason(state)
+        assess(DISABLED, DISABLED_CONFIDENCE, reasons.compact)
+      end
+
+      def rolled_out(state)
+        reasons = [Reason.new(rule: :fully_rolled_out,
+          detail: "enabled with no targeting (one variant served to all); the other branch is never taken — a candidate for removal")]
+        reasons << updated_at_reason(state)
+        assess(ROLLED_OUT, ROLLED_OUT_CONFIDENCE, reasons.compact)
+      end
+
+      def active(_state)
+        reasons = [Reason.new(rule: :active,
+          detail: "enabled with targeting (serving multiple variations); actively evaluated — not a removal candidate")]
+        assess(ACTIVE, ACTIVE_CONFIDENCE, reasons)
+      end
+
+      # An evidence note for a captured last-modified timestamp (deferred time-decay
+      # seed). nil when the snapshot recorded none, so it is compacted out.
+      def updated_at_reason(state)
+        return nil unless state.updated_at
+        Reason.new(rule: :last_modified, detail: "provider last modified this flag at #{state.updated_at}")
+      end
+
+      def assess(status, confidence, reasons)
+        Assessment.new(status: status, confidence: clamp(confidence), reasons: reasons)
+      end
+
+      def clamp(value)
+        value.clamp(0.0, 1.0).round(2)
+      end
+    end
+  end
+end

data/lib/moult/flags.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Moult
+  # Orchestrates the feature-flag analysis: it asks the {FlagScanner} for every
+  # OpenFeature flag-evaluation call site, groups them by flag key, attributes each
+  # site to its enclosing method (best-effort, for the cross-analysis join), and
+  # grades each group through the pure {Flags::Classification} model. The result is
+  # a {FlagsReport} cataloguing flag USAGE.
+  #
+  # When a provider snapshot is supplied (the static<->provider merge, the flags
+  # analogue of the static<->runtime coverage merge), it ALSO joins each flag key to
+  # the provider's recorded state and grades a confidence-graded {Staleness}
+  # candidate — the first real use of the per-finding confidence slot in this slice.
+  # The snapshot is evidence, never proof; nothing here asserts a flag is certainly
+  # stale or dead.
+  #
+  # This is the only layer that joins the facts to symbols and to the provider;
+  # {Classification} and {Staleness} stay pure functions of the observed signals so
+  # they can be pinned in isolation, {FlagScanner} stays the sole keeper of the
+  # OpenFeature call shape, and {Snapshot} the sole keeper of the export format.
+  module Flags
+    module_function
+
+    # @param root [String] absolute analysis root
+    # @param files [Array<String>] absolute Ruby file paths to scan
+    # @param snapshot [Snapshot::FlagSet, nil] a merged provider snapshot; when given,
+    #   each finding gains a confidence-graded staleness candidate joined on flag_key
+    # @return [FlagsReport]
+    def build_report(root:, files:, git_ref: nil, generated_at: nil, snapshot: nil)
+      sites = files.flat_map { |abs| scan(abs, root) }
+      methods = MethodIndex.new(root: root, files: files)
+
+      literal, dynamic = sites.partition { |s| !s.flag_key.nil? }
+      has_dynamic = dynamic.size.positive?
+      findings = literal.group_by(&:flag_key).map { |key, group| finding_for(key, group, methods, snapshot, has_dynamic) }
+      # With a snapshot, strongest staleness candidate first (then refs, then key);
+      # without, most-referenced first. Either way alphabetical by key breaks ties so
+      # output is stable.
+      findings.sort_by! do |f|
+        f.staleness ? [-f.staleness.confidence, -f.reference_count, f.flag_key] : [-f.reference_count, f.flag_key]
+      end
+
+      FlagsReport.new(
+        root: root,
+        findings: findings,
+        dynamic_references: dynamic.size,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        provider_source: snapshot&.source
+      )
+    end
+
+    def scan(abs, root)
+      FlagScanner.scan_file(abs, SymbolId.relative_path(abs, root))
+    rescue
+      []
+    end
+
+    def finding_for(key, sites, methods, snapshot = nil, has_dynamic = false)
+      assessment = Classification.classify(
+        value_types: sites.map(&:value_type),
+        default_values: sites.map(&:default_value)
+      )
+      occurrences = sites
+        .sort_by { |s| [s.path, s.line] }
+        .map { |s| FlagsReport::Occurrence.new(symbol_id: methods.symbol_id_at(s.path, s.line), path: s.path, line: s.line, method_name: s.method_name) }
+      staleness = staleness_for(key, snapshot, has_dynamic)
+      FlagsReport::Finding.new(
+        flag_key: key,
+        value_type: assessment.value_type,
+        reference_count: assessment.reference_count,
+        default_values: assessment.default_values,
+        reasons: assessment.reasons,
+        occurrences: occurrences,
+        staleness: staleness
+      )
+    end
+
+    # The staleness candidate for a key, joined on the literal flag_key (the flags
+    # join key, mirroring how coverage joins on symbol_id). nil when no snapshot was
+    # supplied, leaving the finding byte-for-byte v1-identical.
+    def staleness_for(key, snapshot, has_dynamic)
+      return nil unless snapshot
+      Staleness.classify(state: snapshot.state_for(key), has_dynamic_references: has_dynamic)
+    end
+
+    # Best-effort line -> enclosing-method resolution, reusing the Prism {Parser} so
+    # the minted ids are byte-identical to the hotspots/deadcode/duplication join
+    # keys. We attribute a call site to the innermost method whose span contains its
+    # line; files are parsed lazily and memoised. A reference outside any method
+    # (top-level code) resolves to nil. (Mirrors {Duplication::MethodIndex}.)
+    class MethodIndex
+      def initialize(root:, files:)
+        @abs_by_rel = files.to_h { |abs| [SymbolId.relative_path(abs, root), abs] }
+        @cache = {}
+      end
+
+      # @return [String, nil] symbol_id of the innermost containing method, or nil
+      def symbol_id_at(rel_path, line)
+        method = enclosing_method(rel_path, line)
+        return nil unless method
+        SymbolId.for(path: rel_path, start_line: method.span.start_line, fqname: method.name)
+      end
+
+      private
+
+      def enclosing_method(rel_path, line)
+        methods_for(rel_path)
+          .select { |m| line.between?(m.span.start_line, m.span.end_line) }
+          .min_by { |m| m.span.end_line - m.span.start_line }
+      end
+
+      def methods_for(rel_path)
+        @cache[rel_path] ||= parse(rel_path)
+      end
+
+      def parse(rel_path)
+        abs = @abs_by_rel[rel_path]
+        return [] unless abs
+        Parser.parse_file(abs)
+      rescue
+        []
+      end
+    end
+  end
+end
+
+require_relative "flags/classification"
+require_relative "flags/staleness"
+require_relative "flags/snapshot"
+require_relative "flags_report"

data/lib/moult/flags_report.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Moult
+  # The serialized result model for `moult flags` (schema/flags.schema.json),
+  # sibling to {DuplicationReport}, {DeadCodeReport}, {CoverageReport},
+  # {HealthReport} and {BoundariesReport}. It owns its own JSON envelope and leaves
+  # the other protected contracts untouched.
+  #
+  # Each {Finding} is one flag key and the call sites referencing it. Without a
+  # provider snapshot it carries +confidence: null+ (a flag reference is a recorded
+  # fact) and a {Flags::Classification} signal — the value_type, reference count, and
+  # observed default value(s) — and serializes at schema_version 1.
+  #
+  # When a provider snapshot is merged (the static<->provider merge) each finding
+  # ALSO carries a confidence-graded {Flags::Staleness} candidate (status +
+  # confidence + reasons), the report carries an analysis.provider provenance block,
+  # and the summary a by_staleness_status tally; the envelope reports schema_version
+  # 2. The bump is purely additive: with no snapshot the v2-only blocks are omitted
+  # and the output is byte-for-byte identical to v1. The snapshot is evidence, never
+  # proof — nothing here asserts a flag is certainly stale or dead.
+  class FlagsReport
+    # The serialized shape's two additive versions. v1 = usage only; v2 = usage +
+    # joined staleness candidates (--provider). Bump either only on a breaking change.
+    SCHEMA_VERSION = 1
+    SCHEMA_VERSION_WITH_PROVIDER = 2
+
+    # One reference site of a flag. +symbol_id+ is the best-effort enclosing-method
+    # join key (shared across contracts), nil for a top-level reference. +line+ is
+    # the call-site line; +method+ is the OpenFeature fetch method used (it implies
+    # the value type and whether the _details variant was called).
+    Occurrence = Struct.new(:symbol_id, :path, :line, :method_name) do
+      def to_h
+        {symbol_id: symbol_id, path: path, line: line, method: method_name}
+      end
+    end
+
+    # One flag key. Carries its classification (value_type / reference_count /
+    # default_values) and reasons so the catalogue is auditable. +staleness+ is a
+    # {Flags::Staleness::Assessment} when a provider snapshot was merged, else nil.
+    # +confidence+ is the staleness candidate's confidence when graded, else null (a
+    # reference alone is a fact, the signal is the classification).
+    Finding = Struct.new(:flag_key, :value_type, :reference_count, :default_values, :reasons, :occurrences, :staleness) do
+      def to_h
+        h = {
+          category: Flags::Classification::CATEGORY,
+          confidence: staleness&.confidence,
+          flag_key: flag_key,
+          value_type: value_type,
+          reference_count: reference_count,
+          default_values: default_values,
+          reasons: reasons.map(&:to_h),
+          occurrences: occurrences.map(&:to_h)
+        }
+        # Additive: the staleness block appears only when graded, leaving the v1
+        # finding byte-for-byte unchanged (confidence stays null, no extra key).
+        h[:staleness] = staleness.to_h if staleness
+        h
+      end
+    end
+
+    attr_reader :root, :findings, :dynamic_references, :git_ref, :generated_at, :provider_source
+
+    # @param root [String] absolute analysis root
+    # @param findings [Array<Finding>] ranked, strongest staleness candidate (or
+    #   most-referenced, without a snapshot) first
+    # @param dynamic_references [Integer] flag-evaluation calls whose key was not a
+    #   literal (counted, not catalogued — a static scan cannot resolve the key)
+    # @param provider_source [Flags::Snapshot::Source, nil] provenance of a merged
+    #   provider snapshot; its presence selects schema_version 2 and the v2-only blocks
+    def initialize(root:, findings:, dynamic_references: 0, git_ref: nil, generated_at: nil, provider_source: nil)
+      @root = root
+      @findings = findings
+      @dynamic_references = dynamic_references
+      @git_ref = git_ref
+      @generated_at = generated_at
+      @provider_source = provider_source
+    end
+
+    # @return [Hash] aggregate counts across all flags
+    def summary
+      base = {
+        flags: findings.size,
+        references: findings.sum { |f| f.occurrences.size },
+        dynamic_references: dynamic_references,
+        by_value_type: tally { |f| f.value_type }
+      }
+      # v2-only: the staleness-status tally appears only when a snapshot was merged.
+      base[:by_staleness_status] = staleness_tally if provider_source
+      base
+    end
+
+    def to_h
+      {
+        schema_version: provider_source ? SCHEMA_VERSION_WITH_PROVIDER : SCHEMA_VERSION,
+        tool: {name: "moult", version: Moult::VERSION},
+        analysis: analysis,
+        summary: summary,
+        findings: findings.map(&:to_h)
+      }
+    end
+
+    private
+
+    # Built incrementally so the provider provenance is appended only when present,
+    # leaving the v1 analysis block byte-for-byte unchanged.
+    def analysis
+      block = {
+        root: root,
+        git_ref: git_ref,
+        generated_at: generated_at,
+        scanner: {
+          target: FlagScanner::TARGET,
+          sdk_gem: FlagScanner::SDK_GEM,
+          client_builder: FlagScanner::CLIENT_BUILDER
+        }
+      }
+      block[:provider] = provider_source.to_h if provider_source
+      block
+    end
+
+    # Flag count keyed by staleness status (one per flag, not reference-weighted).
+    def staleness_tally
+      findings.each_with_object(Hash.new(0)) do |finding, acc|
+        acc[finding.staleness.status] += 1 if finding.staleness
+      end
+    end
+
+    # Count flags grouped by the yielded key, reference-weighted so the totals match
+    # the +references+ count.
+    def tally
+      findings.each_with_object(Hash.new(0)) do |finding, acc|
+        acc[yield(finding)] += finding.occurrences.size
+      end
+    end
+  end
+end

data/lib/moult/formatters/boundaries_json.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moult
+  module Formatters
+    # JSON rendering of a {BoundariesReport}. 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 BoundariesJson
+      module_function
+
+      # @param report [BoundariesReport]
+      # @return [String]
+      def render(report)
+        JSON.pretty_generate(report.to_h)
+      end
+    end
+  end
+end

data/lib/moult/formatters/boundaries_table.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable table of architecture-boundary violations. Renders from the same
+    # {BoundariesReport} as the JSON formatter so the two cannot disagree. Sorting
+    # already happened in {Boundaries}; this layer owns column formatting only.
+    #
+    # The heading is deliberate: these are recorded packwerk violations, classified
+    # by severity — never a claim that the code is certainly wrong.
+    module BoundariesTable
+      MAX_FILES = 3
+
+      module_function
+
+      # @param report [BoundariesReport]
+      # @return [String]
+      def render(report)
+        return "Not a packwerk project (no packwerk.yml): no architecture boundaries to check." unless report.configured
+
+        findings = report.findings
+        return "No architecture-boundary violations recorded." if findings.empty?
+
+        headers = %w[SEV TYPE REFERENCING DEFINING CONSTANT FILES]
+        rows = findings.map { |f| row(f) }
+        [heading(report.summary), "", TextTable.render(headers, rows)].join("\n")
+      end
+
+      def heading(summary)
+        by_sev = %w[high medium low].filter_map { |s| "#{summary[:by_severity][s]} #{s}" if summary[:by_severity][s].to_i.positive? }
+        "Architecture-boundary violations (packwerk, recorded — not certainties): " \
+          "#{summary[:findings]} groups, #{summary[:violations]} violations (#{by_sev.join(", ")})"
+      end
+
+      def row(finding)
+        [
+          finding.severity,
+          finding.violation_type,
+          finding.referencing_package,
+          finding.defining_package,
+          finding.constant,
+          files(finding.occurrences)
+        ]
+      end
+
+      def files(occurrences)
+        shown = occurrences.first(MAX_FILES).map(&:path)
+        extra = occurrences.size - shown.size
+        extra.positive? ? "#{shown.join(", ")} (+#{extra} more)" : shown.join(", ")
+      end
+    end
+  end
+end

data/lib/moult/formatters/coverage_json.rb

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

data/lib/moult/formatters/coverage_table.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable runtime coverage map. Renders from the same
+    # {CoverageReport} as the JSON formatter so the two cannot disagree; sorting
+    # already happened in {CoverageReport.build}.
+    module CoverageTable
+      HEADERS = ["RUNTIME", "KIND", "SYMBOL", "LOCATION"].freeze
+      GUTTER = "  "
+
+      module_function
+
+      # @param report [CoverageReport]
+      # @return [String]
+      def render(report)
+        entries = report.entries
+        return "No symbols found." if entries.empty?
+
+        rows = entries.map { |e| row(e, report.root) }
+        [heading(report.summary), "", table(rows)].join("\n")
+      end
+
+      def heading(summary)
+        "Runtime coverage map: #{summary[:hot]} hot, #{summary[:cold]} cold, #{summary[:untracked]} untracked"
+      end
+
+      def row(entry, _root)
+        [
+          entry.runtime.to_s,
+          entry.kind.to_s,
+          entry.name.to_s,
+          location(entry)
+        ]
+      end
+
+      def location(entry)
+        # symbol_id is "<path>:<start_line>:<fqname>"; the path:line prefix is the
+        # most useful location and avoids re-deriving it.
+        path, line, _ = entry.symbol_id.split(":", 3)
+        "#{path}:#{line}"
+      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| cell.ljust(widths[col]) }.join(GUTTER).rstrip
+      end
+    end
+  end
+end

data/lib/moult/formatters/dead_code_json.rb

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

data/lib/moult/formatters/dead_code_table.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Moult
+  module Formatters
+    # Human-readable table of dead-code candidates. Renders from the same
+    # {DeadCodeReport} as the JSON formatter so the two cannot disagree. Sorting
+    # already happened in {DeadCode}; this layer owns column formatting only.
+    #
+    # The heading is deliberate: these are confidence-graded candidates, never
+    # certainties.
+    module DeadCodeTable
+      # Only the CONF column (col 0) is right-aligned.
+      RIGHT_ALIGNED = [0].freeze
+
+      module_function
+
+      # @param report [DeadCodeReport]
+      # @return [String]
+      def render(report)
+        findings = report.findings
+        return "No dead-code candidates found." if findings.empty?
+
+        # The RUNTIME column only appears when coverage was merged, so output
+        # without --coverage is byte-for-byte unchanged from Phase 2.
+        runtime = findings.any? { |f| !f.runtime.nil? }
+        headers = columns(runtime)
+        rows = findings.map { |f| row(f, runtime) }
+        [heading(findings.size), "", TextTable.render(headers, rows, right_aligned: RIGHT_ALIGNED)].join("\n")
+      end
+
+      def columns(runtime)
+        cols = ["CONF", "KIND"]
+        cols << "RUNTIME" if runtime
+        cols + ["SYMBOL", "LOCATION", "TOP REASON"]
+      end
+
+      def heading(count)
+        "Dead-code candidates (confidence-graded — not certainties): #{count} findings"
+      end
+
+      def row(finding, runtime)
+        cells = [conf(finding.confidence), finding.kind.to_s]
+        cells << (finding.runtime&.to_s || "-") if runtime
+        cells + [finding.name.to_s, location(finding), top_reason(finding)]
+      end
+
+      def location(finding)
+        span = finding.span
+        line = span&.start_line
+        line ? "#{finding.path}:#{line}" : finding.path.to_s
+      end
+
+      # The most informative reason is the last applied non-base adjustment;
+      # fall back to the base reason for a bare candidate.
+      def top_reason(finding)
+        reasons = finding.reasons.reject { |r| r.rule == :base_score }
+        chosen = reasons.last || finding.reasons.first
+        chosen ? chosen.detail.to_s : "-"
+      end
+
+      def conf(value)
+        format("%.2f", value)
+      end
+    end
+  end
+end

data/lib/moult/formatters/duplication_json.rb

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