rigortype 0.0.1

data/lib/rigor/cli/type_scan_renderer.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+module Rigor
+  class CLI
+    # Renders a `TypeScanCommand::Report` as either a terminal-friendly text
+    # summary or a JSON document suitable for CI ingestion. Text and JSON
+    # branches share a single source of truth (the `Report` value object) so
+    # the two formats stay in lockstep; that pairing is why this class is a
+    # bit longer than the default class-length budget.
+    class TypeScanRenderer # rubocop:disable Metrics/ClassLength
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(report, format:)
+        case format
+        when "text" then render_text(report)
+        when "json" then render_json(report)
+        else
+          raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+        end
+      end
+
+      private
+
+      def render_text(report)
+        render_text_header(report)
+        render_text_summary(report)
+        render_text_class_table(report)
+        render_text_events(report)
+        render_text_parse_errors(report)
+      end
+
+      def render_text_header(report)
+        files = report.files
+        suffix = files.size == 1 ? "" : "s"
+        @out.puts("Type-of scan: #{files.size} file#{suffix}")
+        files.first(5).each { |f| @out.puts("  - #{f}") }
+        @out.puts("  ... (#{files.size - 5} more)") if files.size > 5
+        @out.puts("")
+      end
+
+      def render_text_summary(report)
+        processed = report.files.size - report.parse_errors.size
+        visited = report.visited_count
+        unrec = report.unrecognized_count
+
+        @out.puts("Summary:")
+        @out.puts("  files processed:   #{processed}")
+        @out.puts("  parse errors:      #{report.parse_errors.size}")
+        @out.puts("  AST nodes visited: #{visited}")
+        @out.puts("  unrecognized:      #{unrec}#{percent_suffix(unrec, visited)}")
+        @out.puts("")
+      end
+
+      def render_text_class_table(report)
+        rows = build_class_rows(report)
+        return if rows.empty?
+
+        width = rows.map { |row| row[:name].size }.max
+        @out.puts("Coverage by node class (unrecognized/visits):")
+        rows.each { |row| @out.puts(format_class_row(row, width)) }
+        @out.puts("")
+      end
+
+      def format_class_row(row, width)
+        suffix = percent_suffix(row[:unrecognized], row[:visits])
+        "  #{row[:name].ljust(width)}  #{row[:unrecognized]}/#{row[:visits]}#{suffix}"
+      end
+
+      def build_class_rows(report)
+        rows = report.visits.map do |klass, visits|
+          unrec = report.unrecognized[klass] || 0
+          { name: klass.name, visits: visits, unrecognized: unrec }
+        end
+        rows.reject! { |row| row[:unrecognized].zero? } unless report.options[:show_recognized]
+        rows.sort_by! do |row|
+          ratio = row[:visits].zero? ? 0.0 : row[:unrecognized].fdiv(row[:visits])
+          [-ratio, -row[:unrecognized], row[:name]]
+        end
+        rows
+      end
+
+      def render_text_events(report)
+        events = report.events
+        return if events.empty?
+
+        limit = report.options[:limit] || events.size
+        shown = events.first(limit)
+        @out.puts("Unrecognized examples (showing #{shown.size} of #{events.size}):")
+        shown.each do |located|
+          @out.puts("  #{located.event.node_class}  @  #{location_text(located)}")
+        end
+        @out.puts("")
+      end
+
+      def render_text_parse_errors(report)
+        return if report.parse_errors.empty?
+
+        @out.puts("Parse errors:")
+        report.parse_errors.each do |entry|
+          @out.puts("  #{entry[:file]}: #{entry[:errors].join('; ')}")
+        end
+      end
+
+      def render_json(report)
+        @out.puts(JSON.pretty_generate(json_payload(report)))
+      end
+
+      def json_payload(report)
+        {
+          files: report.files,
+          summary: {
+            files_processed: report.files.size - report.parse_errors.size,
+            parse_errors: report.parse_errors.size,
+            visited: report.visited_count,
+            unrecognized: report.unrecognized_count,
+            unrecognized_ratio: report.unrecognized_ratio
+          },
+          by_class: by_class_payload(report),
+          events: report.events.map { |located| event_payload(located) },
+          parse_errors: report.parse_errors.map do |entry|
+            { file: entry[:file], errors: entry[:errors] }
+          end
+        }
+      end
+
+      def by_class_payload(report)
+        report.visits.sort_by { |klass, _| klass.name }.to_h do |klass, visits|
+          [klass.name, { visits: visits, unrecognized: report.unrecognized[klass] || 0 }]
+        end
+      end
+
+      def event_payload(located)
+        location = located.event.location
+        payload = {
+          file: located.file,
+          node_class: located.event.node_class.name,
+          family: located.event.family
+        }
+        if location.respond_to?(:start_line)
+          payload[:line] = location.start_line
+          payload[:column] = location.start_column + 1
+        end
+        payload
+      end
+
+      def location_text(located)
+        location = located.event.location
+        return "<no location>" unless location.respond_to?(:start_line)
+
+        "#{located.file}:#{location.start_line}:#{location.start_column + 1}"
+      end
+
+      def percent_suffix(numerator, denominator)
+        return "" if denominator.zero?
+
+        " (#{(numerator.fdiv(denominator) * 100).round(1)}%)"
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_scan_report.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # Aggregated report assembled by `TypeScanCommand` and consumed by
+    # `TypeScanRenderer`. The struct holds per-file paths, accumulated
+    # per-class counts, located fallback events, and any parse errors.
+    Report = Data.define(
+      :files,
+      :parse_errors,
+      :visits,
+      :unrecognized,
+      :events,
+      :options
+    ) do
+      def visited_count
+        visits.values.sum
+      end
+
+      def unrecognized_count
+        unrecognized.values.sum
+      end
+
+      def unrecognized_ratio
+        total = visited_count
+        return 0.0 if total.zero?
+
+        unrecognized_count.fdiv(total)
+      end
+    end
+  end
+end

data/lib/rigor/cli.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+require "yaml"
+
+require_relative "configuration"
+require_relative "version"
+require_relative "analysis/diagnostic"
+require_relative "analysis/result"
+
+module Rigor
+  # The CLI class is a dispatcher: each `run_*` method delegates to a
+  # command-specific class once the command grows beyond a few lines (see
+  # {CLI::TypeOfCommand}). The class-length budget is intentionally relaxed
+  # here so dispatch wiring can live alongside still-inlined commands.
+  class CLI # rubocop:disable Metrics/ClassLength
+    EXIT_USAGE = 64
+
+    HANDLERS = {
+      "check" => :run_check,
+      "init" => :run_init,
+      "type-of" => :run_type_of,
+      "type-scan" => :run_type_scan
+    }.freeze
+
+    def self.start(argv = ARGV, out: $stdout, err: $stderr)
+      new(argv.dup, out: out, err: err).run
+    end
+
+    def initialize(argv, out:, err:)
+      @argv = argv
+      @out = out
+      @err = err
+    end
+
+    def run
+      command = @argv.shift
+
+      case command
+      when nil, "help", "-h", "--help"
+        @out.puts(help)
+        0
+      when "version", "-v", "--version"
+        @out.puts("rigor #{Rigor::VERSION}")
+        0
+      else
+        dispatch(command)
+      end
+    rescue OptionParser::ParseError => e
+      @err.puts(e.message)
+      EXIT_USAGE
+    end
+
+    private
+
+    def dispatch(command)
+      handler = HANDLERS[command]
+      return send(handler) if handler
+
+      @err.puts("Unknown command: #{command}")
+      @err.puts(help)
+      EXIT_USAGE
+    end
+
+    def run_check
+      require_relative "analysis/runner"
+
+      options = {
+        config: Configuration::DEFAULT_PATH,
+        format: "text"
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: rigor check [options] [paths]"
+        opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+      end
+      parser.parse!(@argv)
+
+      configuration = Configuration.load(options.fetch(:config))
+      paths = @argv.empty? ? configuration.paths : @argv
+      result = Analysis::Runner.new(configuration: configuration).run(paths)
+
+      write_result(result, options.fetch(:format))
+      result.success? ? 0 : 1
+    end
+
+    def run_init
+      options = {
+        force: false,
+        path: Configuration::DEFAULT_PATH
+      }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: rigor init [options]"
+        opts.on("--force", "Overwrite an existing configuration file") { options[:force] = true }
+        opts.on("--path=PATH", "Configuration file path") { |value| options[:path] = value }
+      end
+      parser.parse!(@argv)
+
+      path = options.fetch(:path)
+      if File.exist?(path) && !options.fetch(:force)
+        @err.puts("#{path} already exists; use --force to overwrite it")
+        return 1
+      end
+
+      File.write(path, init_template)
+      @out.puts("Created #{path}")
+      0
+    end
+
+    # Renders the starter `.rigor.yml` body. The template
+    # serialises `Configuration::DEFAULTS` (so the on-disk file
+    # round-trips through `Configuration.load`) and prepends a
+    # short header that points the user at the keys they are
+    # most likely to want to edit.
+    def init_template
+      <<~YAML
+        # Rigor configuration. See docs/CURRENT_WORK.md for the
+        # full set of features the analyzer ships in this preview.
+        #
+        # Keys you may want to edit:
+        # - target_ruby: minimum Ruby version your project targets.
+        # - paths:       directories scanned by `rigor check` and
+        #                `rigor type-scan` when no path is given.
+        # - plugins:     reserved for future plugin contributions
+        #                (no plugins are loaded today).
+        # - cache.path:  where Rigor will eventually persist
+        #                analysis results across runs.
+        #
+        # `Rigor::Environment.for_project` automatically loads
+        # the project's `sig/` directory plus a curated stdlib
+        # bundle (pathname, optparse, json, yaml, fileutils,
+        # tempfile, uri, logger, date, prism, rbs). Adding a
+        # `sig/<gem>.rbs` file under `sig/` is the simplest way
+        # to extend type coverage today.
+        #{YAML.dump(Configuration::DEFAULTS).sub(/\A---\n/, '')}
+      YAML
+    end
+
+    def run_type_of
+      require_relative "cli/type_of_command"
+
+      TypeOfCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def run_type_scan
+      require_relative "cli/type_scan_command"
+
+      TypeScanCommand.new(argv: @argv, out: @out, err: @err).run
+    end
+
+    def write_result(result, format)
+      case format
+      when "json"
+        @out.puts(JSON.pretty_generate(result.to_h))
+      when "text"
+        write_text_result(result)
+      else
+        raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+      end
+    end
+
+    # Text output adds a one-line summary so users see the
+    # diagnostic-count immediately. The summary distinguishes
+    # the success and failure cases and reports the affected
+    # file count for failures.
+    def write_text_result(result)
+      if result.success?
+        @out.puts("No diagnostics")
+        return
+      end
+
+      result.diagnostics.each { |diagnostic| @out.puts(diagnostic) }
+      file_count = result.diagnostics.map(&:path).uniq.size
+      @out.puts("")
+      @out.puts("#{result.error_count} error(s) in #{file_count} file(s)")
+    end
+
+    def help
+      <<~HELP
+        Usage: rigor <command> [options]
+
+        Commands:
+          check      Analyze Ruby source files
+          init       Create a starter .rigor.yml
+          type-of    Print the inferred type at FILE:LINE:COL
+          type-scan  Report Scope#type_of coverage across PATHs
+          version    Print the Rigor version
+          help       Print this help
+      HELP
+    end
+  end
+end

data/lib/rigor/configuration.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rigor
+  class Configuration
+    DEFAULT_PATH = ".rigor.yml"
+    DEFAULTS = {
+      "target_ruby" => "4.0",
+      "paths" => ["lib"],
+      "plugins" => [],
+      "cache" => {
+        "path" => ".rigor/cache"
+      }
+    }.freeze
+
+    attr_reader :target_ruby, :paths, :plugins, :cache_path
+
+    def self.load(path = DEFAULT_PATH)
+      data = if File.exist?(path)
+               YAML.safe_load_file(path, aliases: false) || {}
+             else
+               {}
+             end
+
+      new(DEFAULTS.merge(data))
+    end
+
+    def initialize(data = DEFAULTS)
+      cache = DEFAULTS.fetch("cache").merge(data.fetch("cache", {}))
+
+      @target_ruby = data.fetch("target_ruby", DEFAULTS.fetch("target_ruby")).to_s
+      @paths = Array(data.fetch("paths", DEFAULTS.fetch("paths"))).map(&:to_s)
+      @plugins = Array(data.fetch("plugins", DEFAULTS.fetch("plugins"))).map(&:to_s)
+      @cache_path = cache.fetch("path").to_s
+    end
+
+    def to_h
+      {
+        "target_ruby" => target_ruby,
+        "paths" => paths,
+        "plugins" => plugins,
+        "cache" => {
+          "path" => cache_path
+        }
+      }
+    end
+  end
+end

data/lib/rigor/environment/class_registry.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../type"
+
+module Rigor
+  class Environment
+    # Resolves Ruby Class/Module objects to Rigor::Type::Nominal instances.
+    # The hardcoded list spans the core classes the literal typer (Slice 1)
+    # and the constant-resolution path (Slice 2 strengthening) need.
+    # Slice 4 will extend the registry by reading RBS Definitions through
+    # Rigor::Environment::RbsLoader.
+    #
+    # See docs/internal-spec/inference-engine.md for the binding contract
+    # (every entry below MUST always be recognised).
+    class ClassRegistry
+      SLICE_1_BUILT_INS = [
+        Integer,
+        Float,
+        String,
+        Symbol,
+        NilClass,
+        TrueClass,
+        FalseClass,
+        Object,
+        BasicObject
+      ].freeze
+
+      # Common Ruby core classes that user code routinely names by constant
+      # reference. Adding them to the registry lets `nominal_for_name`
+      # resolve `Array`, `Hash`, etc. without each call site re-listing
+      # them; Slice 4's RBS loader will subsume these once it lands.
+      SLICE_2_BUILT_INS = [
+        Array,
+        Hash,
+        Range,
+        Regexp,
+        Proc,
+        Method,
+        Module,
+        Class,
+        Numeric,
+        Comparable,
+        Enumerable,
+        Exception,
+        StandardError,
+        RuntimeError,
+        ArgumentError,
+        TypeError,
+        NameError,
+        NoMethodError,
+        KeyError,
+        IndexError,
+        RangeError,
+        ZeroDivisionError,
+        IO,
+        File,
+        Dir,
+        Encoding
+      ].freeze
+
+      CORE_BUILT_INS = (SLICE_1_BUILT_INS + SLICE_2_BUILT_INS).freeze
+
+      class << self
+        def default
+          @default ||= build_default
+        end
+
+        private
+
+        def build_default
+          new.tap do |registry|
+            CORE_BUILT_INS.each { |klass| registry.register(klass) }
+          end.freeze
+        end
+      end
+
+      def initialize
+        @nominals = {}
+        @class_objects = {}
+      end
+
+      def register(class_object)
+        raise ArgumentError, "expected Class or Module, got #{class_object.class}" unless class_object.is_a?(Module)
+        raise ArgumentError, "anonymous class has no name" if class_object.name.nil?
+
+        @nominals[class_object.name] ||= Type::Combinator.nominal_of(class_object)
+        @class_objects[class_object.name] ||= class_object
+        self
+      end
+
+      def registered?(class_object)
+        return false unless class_object.is_a?(Module) && class_object.name
+
+        @nominals.key?(class_object.name)
+      end
+
+      def nominal_for(class_object)
+        unless registered?(class_object)
+          raise KeyError, "Rigor::Environment::ClassRegistry has no entry for #{class_object.inspect}"
+        end
+
+        @nominals.fetch(class_object.name)
+      end
+
+      # Nil-safe lookup by class name. Accepts Symbol or String. Returns the
+      # registered Rigor::Type::Nominal, or nil when the name is unknown.
+      # Used by ExpressionTyper to resolve Prism::ConstantReadNode and
+      # Prism::ConstantPathNode under the fail-soft policy: unknown names
+      # MUST NOT raise and MUST flow through the engine's tracer.
+      def nominal_for_name(name)
+        return nil if name.nil?
+
+        @nominals[name.to_s]
+      end
+
+      def class_ordering(lhs, rhs)
+        lhs = normalize_name(lhs)
+        rhs = normalize_name(rhs)
+        return :equal if lhs == rhs
+
+        lhs_class = @class_objects[lhs]
+        rhs_class = @class_objects[rhs]
+        return :unknown if lhs_class.nil? || rhs_class.nil?
+
+        if lhs_class <= rhs_class
+          :subclass
+        elsif rhs_class <= lhs_class
+          :superclass
+        else
+          :disjoint
+        end
+      end
+
+      private
+
+      def normalize_name(name)
+        name.to_s.delete_prefix("::")
+      end
+    end
+  end
+end

data/lib/rigor/environment/rbs_hierarchy.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Rigor
+  class Environment
+    # Small hierarchy oracle backed by RBS instance definitions.
+    class RbsHierarchy
+      def initialize(loader)
+        @loader = loader
+        @ancestor_names_cache = {}
+        @class_ordering_cache = {}
+      end
+
+      def class_ordering(lhs, rhs)
+        lhs = normalize_name(lhs)
+        rhs = normalize_name(rhs)
+        return :equal if lhs == rhs
+
+        key = [lhs, rhs]
+        return @class_ordering_cache[key] if @class_ordering_cache.key?(key)
+
+        @class_ordering_cache[key] = compute_class_ordering(lhs, rhs)
+      end
+
+      private
+
+      attr_reader :loader
+
+      def compute_class_ordering(lhs, rhs)
+        return :unknown unless loader.class_known?(lhs) && loader.class_known?(rhs)
+
+        lhs_ancestors = ancestor_names(lhs)
+        rhs_ancestors = ancestor_names(rhs)
+        return :unknown if lhs_ancestors.empty? || rhs_ancestors.empty?
+
+        if lhs_ancestors.include?(rhs)
+          :subclass
+        elsif rhs_ancestors.include?(lhs)
+          :superclass
+        else
+          :disjoint
+        end
+      end
+
+      def ancestor_names(class_name)
+        key = normalize_name(class_name)
+        return @ancestor_names_cache[key] if @ancestor_names_cache.key?(key)
+
+        definition = loader.instance_definition(key)
+        @ancestor_names_cache[key] =
+          if definition
+            definition.ancestors.ancestors.map { |ancestor| normalize_name(ancestor.name.to_s) }.uniq.freeze
+          else
+            [].freeze
+          end
+      rescue StandardError
+        @ancestor_names_cache[key] = [].freeze
+      end
+
+      def normalize_name(name)
+        name.to_s.delete_prefix("::")
+      end
+    end
+  end
+end