moult 0.1.0

data/lib/moult/cli/coverage_command.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult coverage [PATH] --coverage FILE` — a per-symbol hot/cold/untracked
+    # map resolved from a local coverage file. Thin layer: parse options, build
+    # the index, load the dataset, drive {CoverageReport.build}, format. The map
+    # is diagnostic; it makes no dead-code claim (see `moult deadcode --coverage`
+    # for the confidence merge).
+    class CoverageCommand
+      VALID_FORMATS = %i[auto simplecov coverage].freeze
+
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        unless options[:coverage]
+          warn "moult: coverage requires --coverage PATH"
+          warn @parser
+          return 1
+        end
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        puts render(analyze(root, options), options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = {format: :table, coverage: nil, coverage_format: :auto, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult coverage [PATH] --coverage FILE [options]"
+          o.separator ""
+          o.separator "Options:"
+          o.on("--coverage PATH", "Local coverage file (SimpleCov .resultset.json or a Coverage.result dump)") { |v| options[:coverage] = v }
+          o.on("--coverage-format FORMAT", VALID_FORMATS, "Coverage format: auto (default), simplecov, or coverage") { |v| options[:coverage_format] = v }
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir = File.directory?(root) ? root : File.dirname(root)
+        files = File.directory?(root) ? Discovery.ruby_files(root) : [root]
+
+        index = Index.build(root: root_dir, paths: files)
+        dataset = Coverage.load(options[:coverage], root: root_dir, format: options[:coverage_format])
+        note(options, "loaded #{dataset.entries.size} covered files (#{dataset.source.backend}); #{dataset.unmatched_count} outside root ignored.")
+
+        CoverageReport.build(
+          index: index,
+          coverage: dataset,
+          root: root_dir,
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601,
+          backend_version: rubydex_version
+        )
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::CoverageJson.render(report)
+        else Formatters::CoverageTable.render(report)
+        end
+      end
+
+      def rubydex_version
+        defined?(Rubydex::VERSION) ? Rubydex::VERSION : nil
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/dead_code_command.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult deadcode [PATH]` — list confidence-graded dead-code candidates.
+    # Thin layer: parse options, build the index + Rails awareness, drive the
+    # library, hand the {DeadCodeReport} to a formatter. Report-only: exit 0 on
+    # success, non-zero only on error.
+    class DeadCodeCommand
+      DEFAULT_MIN_CONFIDENCE = 0.0
+
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      VALID_COVERAGE_FORMATS = %i[auto simplecov coverage].freeze
+
+      def parse(argv)
+        options = {format: :table, min_confidence: DEFAULT_MIN_CONFIDENCE, rails: true, quiet: false,
+                   coverage: nil, coverage_format: :auto}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult deadcode [PATH] [options]"
+          o.separator ""
+          o.separator "Options:"
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--min-confidence N", Float, "Hide findings below this confidence 0..1 (default #{DEFAULT_MIN_CONFIDENCE})") { |v| options[:min_confidence] = v }
+          o.on("--[no-]rails", "Apply Rails entrypoint awareness (default on)") { |v| options[:rails] = v }
+          o.on("--coverage PATH", "Merge a local coverage file as runtime evidence (SimpleCov .resultset.json or a Coverage.result dump)") { |v| options[:coverage] = v }
+          o.on("--coverage-format FORMAT", VALID_COVERAGE_FORMATS, "Coverage format: auto (default), simplecov, or coverage") { |v| options[:coverage_format] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir, files = Support.discover(root)
+        index = Index.build(root: root_dir, paths: files)
+        rails = Support.build_rails(root_dir, files, enabled: options[:rails])
+        coverage = load_coverage(root_dir, options)
+        note(options, "analysed #{files.size} files; index #{index.resolved? ? "resolved" : "unresolved"}.")
+        unless rails.rails?
+          note(options, "not a Rails app (or --no-rails); framework entrypoint awareness is off.")
+        end
+
+        DeadCode.build_report(
+          root: root_dir,
+          files: files,
+          index: index,
+          rails: rails,
+          min_confidence: options[:min_confidence],
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601,
+          backend_version: rubydex_version,
+          coverage: coverage
+        )
+      end
+
+      def load_coverage(root_dir, options)
+        return nil unless options[:coverage]
+        dataset = Coverage.load(options[:coverage], root: root_dir, format: options[:coverage_format])
+        note(options, "merged #{dataset.entries.size} covered files (#{dataset.source.backend}); #{dataset.unmatched_count} outside root ignored.")
+        dataset
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::DeadCodeJson.render(report)
+        else Formatters::DeadCodeTable.render(report)
+        end
+      end
+
+      def rubydex_version
+        defined?(Rubydex::VERSION) ? Rubydex::VERSION : nil
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/duplication_command.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult duplication [PATH]` — list confidence-graded structural-clone groups.
+    # Thin layer: parse options, discover files, drive the library, hand the
+    # {DuplicationReport} to a formatter. Report-only: exit 0 on success, non-zero
+    # only on error.
+    class DuplicationCommand
+      DEFAULT_MIN_CONFIDENCE = 0.0
+
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = {format: :table, min_mass: Clones::DEFAULT_MIN_MASS, fuzzy: false,
+                   min_confidence: DEFAULT_MIN_CONFIDENCE, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult duplication [PATH] [options]"
+          o.separator ""
+          o.separator "Options:"
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--min-mass N", Integer, "Ignore clones below this structural mass (default #{Clones::DEFAULT_MIN_MASS})") { |v| options[:min_mass] = v }
+          o.on("--[no-]fuzzy", "Also report near-matches, not just structural-equivalents (default off)") { |v| options[:fuzzy] = v }
+          o.on("--min-confidence N", Float, "Hide findings below this confidence 0..1 (default #{DEFAULT_MIN_CONFIDENCE})") { |v| options[:min_confidence] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir = File.directory?(root) ? root : File.dirname(root)
+        files = File.directory?(root) ? Discovery.ruby_files(root) : [root]
+        mode = options[:fuzzy] ? ", fuzzy" : ""
+        note(options, "scanned #{files.size} files for duplication (flay, min-mass #{options[:min_mass]}#{mode}).")
+
+        Duplication.build_report(
+          root: root_dir,
+          files: files,
+          min_mass: options[:min_mass],
+          fuzzy: options[:fuzzy],
+          min_confidence: options[:min_confidence],
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601
+        )
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::DuplicationJson.render(report)
+        else Formatters::DuplicationTable.render(report)
+        end
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/flags_command.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult flags [PATH]` — catalogue OpenFeature feature-flag references found by a
+    # static Prism scan. Thin layer: parse options, discover files, drive the
+    # library, hand the {FlagsReport} to a formatter. Report-only: exit 0 on success
+    # (including when no flags are found), non-zero only on error.
+    class FlagsCommand
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      VALID_PROVIDER_FORMATS = %i[auto flagd].freeze
+
+      def parse(argv)
+        options = {format: :table, quiet: false, provider: nil, provider_format: :auto}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult flags [PATH] [options]"
+          o.separator ""
+          o.separator "Options:"
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--provider PATH", "Merge a local OpenFeature provider snapshot (a flagd flag-definition export) for confidence-graded staleness candidates") { |v| options[:provider] = v }
+          o.on("--provider-format FORMAT", VALID_PROVIDER_FORMATS, "Provider snapshot format: auto (default) or flagd") { |v| options[:provider_format] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir = File.directory?(root) ? root : File.dirname(root)
+        files = File.directory?(root) ? Discovery.ruby_files(root) : [root]
+        snapshot = load_snapshot(options)
+        report = Flags.build_report(
+          root: root_dir,
+          files: files,
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601,
+          snapshot: snapshot
+        )
+        note(options, "scanned #{files.size} files for OpenFeature flag references: #{report.summary[:flags]} flags.")
+        report
+      end
+
+      def load_snapshot(options)
+        return nil unless options[:provider]
+        set = Flags::Snapshot.load(options[:provider], format: options[:provider_format])
+        note(options, "merged provider snapshot (#{set.source.backend}): #{set.states.size} flags known to the provider.")
+        set
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::FlagsJson.render(report)
+        else Formatters::FlagsTable.render(report)
+        end
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/gate_command.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult gate [PATH]` — the diff-aware PR risk gate. Thin layer: parse options,
+    # build the index + Rails awareness, resolve the policy (defaults, overridable
+    # via .moult.yml), drive {Gate.build_report}, hand the {GateReport} to a
+    # formatter. Holds NO policy logic.
+    #
+    # Exit code (the one command in Moult that renders a verdict, so it is the one
+    # exception to the repo-wide "1 = error" convention):
+    #   0 = gate passed
+    #   1 = gate failed (policy violated)
+    #   2 = tool error (bad option, missing path, unresolvable diff, …)
+    class GateCommand
+      PASS = 0
+      FAIL = 1
+      ERROR = 2
+
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help if options[:help]
+
+        execute(options)
+      rescue OptionParser::ParseError, Moult::Error => e
+        warn "moult: #{e.message}"
+        ERROR
+      rescue => e
+        warn "moult: #{e.message}"
+        ERROR
+      end
+
+      private
+
+      def execute(options)
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return ERROR
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        (report.verdict == "pass") ? PASS : FAIL
+      end
+
+      def parse(argv)
+        options = {format: :table, base: "origin/main", scope: :diff,
+                   config: nil, rails: true, quiet: false}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult gate [PATH] [options]"
+          o.separator ""
+          o.separator "Diff-aware PR risk gate: scopes the analyses to the code changed since a"
+          o.separator "base ref, applies an explicit policy, and exits non-zero when violated."
+          o.separator ""
+          o.separator "Options:"
+          o.on("--base REF", "Base ref for the diff (default 'origin/main'); gate uses merge-base(REF, HEAD)") { |v| options[:base] = v }
+          o.on("--scope SCOPE", [:diff, :all], "What to gate: diff (default, new code only) or all (whole codebase)") { |v| options[:scope] = v }
+          o.on("--format FORMAT", [:table, :json, :github, :sarif], "Output: table (default), json, github (annotations), or sarif") { |v| options[:format] = v }
+          o.on("--config FILE", "Policy overrides file (default: .moult.yml at the root, if present)") { |v| options[:config] = v }
+          o.on("--[no-]rails", "Apply Rails entrypoint awareness to dead code (default on)") { |v| options[:rails] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help
+        puts @parser
+        PASS
+      end
+
+      def analyze(root, options)
+        root_dir, files = Support.discover(root)
+        index = Index.build(root: root_dir, paths: files)
+        rails = Support.build_rails(root_dir, files, enabled: options[:rails])
+        policy = Gate::Config.policy_for(root: root_dir, config_path: options[:config])
+        note(options, "gating #{files.size} files (scope: #{options[:scope]}, policy: #{policy.source}); index #{index.resolved? ? "resolved" : "unresolved"}.")
+
+        Gate.build_report(
+          root: root_dir,
+          files: files,
+          index: index,
+          rails: rails,
+          base_ref: options[:base],
+          scope: options[:scope],
+          policy: policy,
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601
+        )
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::GateJson.render(report)
+        when :github then Formatters::GateGithub.render(report)
+        when :sarif then Formatters::GateSarif.render(report)
+        else Formatters::GateTable.render(report)
+        end
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end

data/lib/moult/cli/health_command.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "optparse"
+require "time"
+
+module Moult
+  class CLI
+    # `moult health [PATH]` — a composite, auditable health score aggregated from
+    # the other analyses. Thin layer: parse options, build the index + Rails
+    # awareness (+ optional coverage), drive {Health.build_report}, hand the
+    # {HealthReport} to a formatter. Report-only: exit 0 on success (even on a low
+    # score — the PR gate is Phase 4), non-zero only on a hard error.
+    class HealthCommand
+      VALID_COVERAGE_FORMATS = %i[auto simplecov coverage].freeze
+
+      # @return [Integer] process exit status
+      def run(argv)
+        options = parse(argv)
+        return puts_help(options) if options[:help]
+
+        root = File.expand_path(options[:path])
+        unless File.exist?(root)
+          warn "moult: no such file or directory: #{options[:path]}"
+          return 1
+        end
+
+        report = analyze(root, options)
+        puts render(report, options)
+        0
+      rescue OptionParser::ParseError => e
+        warn "moult: #{e.message}"
+        1
+      rescue => e
+        warn "moult: #{e.message}"
+        1
+      end
+
+      private
+
+      def parse(argv)
+        options = {format: :table, rails: true, quiet: false,
+                   coverage: nil, coverage_format: :auto, since: Churn::DEFAULT_SINCE}
+        @parser = OptionParser.new do |o|
+          o.banner = "Usage: moult health [PATH] [options]"
+          o.separator ""
+          o.separator "Aggregates complexity, dead code, duplication and (optionally) runtime"
+          o.separator "coverage into one confidence-graded health score. Report-only."
+          o.separator ""
+          o.separator "Options:"
+          o.on("--format FORMAT", [:table, :json], "Output format: table (default) or json") { |v| options[:format] = v }
+          o.on("--coverage PATH", "Merge a local coverage file (SimpleCov .resultset.json or a Coverage.result dump)") { |v| options[:coverage] = v }
+          o.on("--coverage-format FORMAT", VALID_COVERAGE_FORMATS, "Coverage format: auto (default), simplecov, or coverage") { |v| options[:coverage_format] = v }
+          o.on("--[no-]rails", "Apply Rails entrypoint awareness to dead code (default on)") { |v| options[:rails] = v }
+          o.on("--since DATE", "Churn window start for complexity, any git --since value (default '#{Churn::DEFAULT_SINCE}')") { |v| options[:since] = v }
+          o.on("--quiet", "Suppress informational notes on stderr") { options[:quiet] = true }
+          o.on("-h", "--help", "Show this message") { options[:help] = true }
+        end
+        @parser.permute!(argv)
+        options[:path] = argv.shift || "."
+        options
+      end
+
+      def puts_help(_options)
+        puts @parser
+        0
+      end
+
+      def analyze(root, options)
+        root_dir, files = Support.discover(root)
+        index = Index.build(root: root_dir, paths: files)
+        rails = Support.build_rails(root_dir, files, enabled: options[:rails])
+        coverage = load_coverage(root_dir, options)
+        merged = coverage ? ", coverage merged" : ""
+        note(options, "scored #{files.size} files; index #{index.resolved? ? "resolved" : "unresolved"}#{merged}.")
+
+        Health.build_report(
+          root: root_dir,
+          files: files,
+          index: index,
+          rails: rails,
+          coverage: coverage,
+          since: options[:since],
+          git_ref: Git.head_ref(root_dir),
+          generated_at: Time.now.utc.iso8601,
+          churn_window: window_label(options[:since]),
+          churn_since: explicit_since(options[:since])
+        )
+      end
+
+      def load_coverage(root_dir, options)
+        return nil unless options[:coverage]
+        dataset = Coverage.load(options[:coverage], root: root_dir, format: options[:coverage_format])
+        note(options, "merged #{dataset.entries.size} covered files (#{dataset.source.backend}); #{dataset.unmatched_count} outside root ignored.")
+        dataset
+      end
+
+      def render(report, options)
+        case options[:format]
+        when :json then Formatters::HealthJson.render(report)
+        else Formatters::HealthTable.render(report)
+        end
+      end
+
+      def window_label(since)
+        (since == Churn::DEFAULT_SINCE) ? "last 12 months" : "since #{since}"
+      end
+
+      def explicit_since(since)
+        (since == Churn::DEFAULT_SINCE) ? nil : since
+      end
+
+      def note(options, message)
+        warn "moult: #{message}" unless options[:quiet]
+      end
+    end
+  end
+end