rigortype 0.0.1

data/lib/rigor/analysis/runner.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../inference/scope_indexer"
+require_relative "check_rules"
+require_relative "diagnostic"
+require_relative "result"
+
+module Rigor
+  module Analysis
+    class Runner
+      RUBY_GLOB = "**/*.rb"
+
+      def initialize(configuration:)
+        @configuration = configuration
+      end
+
+      # Walks every Ruby file under `paths`, parses it, builds a
+      # per-node scope index through
+      # `Rigor::Inference::ScopeIndexer`, and runs the
+      # `Rigor::Analysis::CheckRules` catalogue over it. Returns
+      # a `Rigor::Analysis::Result` aggregating every produced
+      # diagnostic plus any Prism parse errors. The Environment
+      # is built once at run start through `Environment.for_project`
+      # so all files share the same RBS load.
+      def run(paths = @configuration.paths)
+        environment = Environment.for_project
+        expansion = expand_paths(paths)
+
+        diagnostics = expansion.fetch(:errors)
+        diagnostics += expansion.fetch(:files).flat_map { |path| analyze_file(path, environment) }
+
+        Result.new(diagnostics: diagnostics)
+      end
+
+      private
+
+      # Resolves the user-supplied path list into:
+      # - `:files`  — the concrete `.rb` files to analyze.
+      # - `:errors` — `Diagnostic` entries for each path that
+      #   does not exist or is not a recognisable Ruby source.
+      #
+      # Surfacing path errors is a first-preview must-have:
+      # `rigor check ./does_not_exist.rb` previously exited
+      # cleanly with no output, which silently masked typos.
+      def expand_paths(paths)
+        files = []
+        errors = []
+        Array(paths).each do |path|
+          if File.directory?(path)
+            files.concat(Dir.glob(File.join(path, RUBY_GLOB)))
+          elsif File.file?(path) && path.end_with?(".rb")
+            files << path
+          elsif File.exist?(path)
+            errors << path_error(path, "not a Ruby file (expected `.rb` or a directory)")
+          else
+            errors << path_error(path, "no such file or directory")
+          end
+        end
+        { files: files, errors: errors }
+      end
+
+      def path_error(path, message)
+        Diagnostic.new(
+          path: path,
+          line: 1,
+          column: 1,
+          message: message,
+          severity: :error
+        )
+      end
+
+      def analyze_file(path, environment)
+        parse_result = Prism.parse_file(path)
+        return parse_diagnostics(path, parse_result) unless parse_result.errors.empty?
+
+        scope = Scope.empty(environment: environment)
+        index = Inference::ScopeIndexer.index(parse_result.value, default_scope: scope)
+        CheckRules.diagnose(path: path, root: parse_result.value, scope_index: index)
+      rescue Errno::ENOENT => e
+        [
+          Diagnostic.new(
+            path: path,
+            line: 1,
+            column: 1,
+            message: e.message,
+            severity: :error
+          )
+        ]
+      rescue StandardError => e
+        [
+          Diagnostic.new(
+            path: path,
+            line: 1,
+            column: 1,
+            message: "internal analyzer error: #{e.class}: #{e.message}",
+            severity: :error
+          )
+        ]
+      end
+
+      def parse_diagnostics(path, parse_result)
+        parse_result.errors.map do |error|
+          location = error.location
+          Diagnostic.new(
+            path: path,
+            line: location.start_line,
+            column: location.start_column + 1,
+            message: error.message,
+            severity: :error
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rigor/ast/type_node.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rigor
+  module AST
+    # A virtual node that wraps a Rigor::Type. Allows callers to ask
+    # "what would the analyzer infer at this position if the value's type
+    # were T?" without constructing a real Prism expression.
+    #
+    # Rigor::Scope#type_of(TypeNode.new(t)) MUST return a structurally-
+    # equal t. The engine MUST NOT modify or annotate the wrapped type.
+    #
+    # Inspired by PHPStan's TypeExpr (a synthetic Expr that returns a
+    # specific Type from $scope->getType). The Rigor counterpart is
+    # spelled "TypeNode" to align with Prism's "Node" suffix convention.
+    class TypeNode
+      include Node
+
+      attr_reader :type
+
+      def initialize(type)
+        raise ArgumentError, "TypeNode requires a non-nil Rigor::Type" if type.nil?
+
+        @type = type
+        freeze
+      end
+
+      def ==(other)
+        other.is_a?(TypeNode) && type == other.type
+      end
+      alias eql? ==
+
+      def hash
+        [TypeNode, type].hash
+      end
+
+      def inspect
+        "#<Rigor::AST::TypeNode #{type.describe(:short)}>"
+      end
+    end
+  end
+end

data/lib/rigor/ast.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Rigor
+  # Synthetic AST nodes accepted by Rigor::Scope#type_of alongside real
+  # Prism nodes. Rigor::AST::Node is a documentation-only marker module
+  # that production code uses to detect virtual-node arguments. Concrete
+  # virtual node classes include Rigor::AST::Node and provide whatever
+  # node-specific data the engine needs to translate them into a
+  # Rigor::Type.
+  #
+  # The contract for virtual nodes lives in
+  # docs/internal-spec/inference-engine.md; the rationale and the rejected
+  # alternative of specialising type classes for operator-method dispatch
+  # live in docs/adr/4-type-inference-engine.md.
+  module AST
+    # Marker module included by every synthetic node. Carries no behaviour.
+    module Node
+    end
+  end
+end
+
+require_relative "ast/type_node"

data/lib/rigor/cli/type_of_command.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "optionparser"
+require "prism"
+
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../source/node_locator"
+require_relative "../inference/fallback_tracer"
+require_relative "../inference/scope_indexer"
+require_relative "type_of_renderer"
+
+module Rigor
+  class CLI
+    # Executes the `rigor type-of` command.
+    #
+    # The command is a thin probe over `Rigor::Scope#type_of`: it locates the
+    # deepest expression at a `(file, line, column)` triple and prints the
+    # inferred type, RBS erasure, and (optionally) the recorded fail-soft
+    # fallbacks.
+    #
+    # Encapsulating the command in its own class keeps `Rigor::CLI` focused on
+    # dispatching and lets us evolve the type-of UX (extra flags, watch mode,
+    # streaming output) without bloating the CLI shell. Output formatting is
+    # delegated to {TypeOfRenderer}.
+    class TypeOfCommand
+      USAGE = "Usage: rigor type-of [options] FILE:LINE:COL"
+
+      Result = Data.define(:file, :line, :column, :node, :type, :tracer)
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+
+        target = parse_position_argument(@argv)
+        return CLI::EXIT_USAGE if target.nil?
+
+        execute(target: target, options: options)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", trace: false }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+          opts.on("--trace", "Record fail-soft fallbacks via FallbackTracer") { options[:trace] = true }
+        end
+        parser.parse!(@argv)
+
+        options
+      end
+
+      def execute(target:, options:)
+        file, line, column = target
+        return 1 unless file_exists?(file)
+
+        source = File.read(file)
+        parse_result = Prism.parse(source, filepath: file)
+        return 1 if parse_errors?(parse_result, file)
+
+        node = locate_node(source: source, root: parse_result.value, file: file, line: line, column: column)
+        return CLI::EXIT_USAGE if node == :out_of_range
+        return 1 if node.nil?
+
+        tracer = options[:trace] ? Inference::FallbackTracer.new : nil
+        base_scope = Scope.empty(environment: project_environment(file))
+
+        # Build a per-node scope index so locals bound earlier in the
+        # file flow into the scope used to type the queried node. We
+        # build the index with no tracer attached (it would otherwise
+        # double-record fallback events with the second-pass type_of
+        # call below), then look up the scope visible at the queried
+        # node and run the actual probe under it.
+        scope_index = Inference::ScopeIndexer.index(parse_result.value, default_scope: base_scope)
+        node_scope = scope_index[node]
+
+        type = node_scope.type_of(node, tracer: tracer)
+        result = Result.new(file: file, line: line, column: column, node: node, type: type, tracer: tracer)
+
+        TypeOfRenderer.new(out: @out).render(result, format: options.fetch(:format))
+        0
+      end
+
+      # Builds a project-aware environment relative to the probed file.
+      # Project-RBS auto-detection roots at CWD today; future work will
+      # walk parent directories to find the enclosing `Gemfile`/`*.gemspec`
+      # so probes against files outside the current process's CWD still
+      # see the right `sig/` tree.
+      def project_environment(_file)
+        Environment.for_project
+      end
+
+      def file_exists?(file)
+        return true if File.file?(file)
+
+        @err.puts("type-of: file not found: #{file}")
+        false
+      end
+
+      def parse_errors?(result, file)
+        return false if result.errors.empty?
+
+        result.errors.each { |error| @err.puts("#{file}:#{error.location.start_line}: #{error.message}") }
+        true
+      end
+
+      def locate_node(source:, root:, file:, line:, column:)
+        node = Source::NodeLocator.at_position(source: source, root: root, line: line, column: column)
+        @err.puts("type-of: no expression found at #{file}:#{line}:#{column}") if node.nil?
+        node
+      rescue Source::NodeLocator::OutOfRangeError => e
+        @err.puts("type-of: #{e.message}")
+        :out_of_range
+      end
+
+      def parse_position_argument(argv)
+        case argv.size
+        when 1
+          parse_colon_form(argv[0])
+        when 3
+          decode_position(*argv)
+        else
+          @err.puts("type-of: expected FILE:LINE:COL or FILE LINE COL")
+          @err.puts(USAGE)
+          nil
+        end
+      end
+
+      def parse_colon_form(arg)
+        parts = arg.split(":")
+        if parts.size < 3
+          @err.puts("type-of: expected FILE:LINE:COL, got #{arg.inspect}")
+          @err.puts(USAGE)
+          return nil
+        end
+
+        column = parts.pop
+        line = parts.pop
+        file = parts.join(":")
+        decode_position(file, line, column)
+      end
+
+      def decode_position(file, line, column)
+        [file, Integer(line, 10), Integer(column, 10)]
+      rescue ArgumentError
+        @err.puts("type-of: line and column must be integers")
+        nil
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_of_renderer.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+
+module Rigor
+  class CLI
+    # Renders a `TypeOfCommand::Result` as either human-readable text or a
+    # machine-readable JSON document.
+    #
+    # The renderer is a separate concern from the command itself so that future
+    # output formats (sexp, lsp-style hover payloads, color decoration) can
+    # plug in without disturbing argument parsing or the inference call site.
+    class TypeOfRenderer
+      def initialize(out:)
+        @out = out
+      end
+
+      def render(result, format:)
+        case format
+        when "text" then render_text(result)
+        when "json" then render_json(result)
+        else
+          raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+        end
+      end
+
+      private
+
+      def render_text(result)
+        @out.puts("#{result.file}:#{result.line}:#{result.column}")
+        @out.puts("node:    #{result.node.class}")
+        @out.puts("type:    #{result.type.describe}")
+        @out.puts("erased:  #{result.type.erase_to_rbs}")
+        render_text_fallbacks(result)
+      end
+
+      def render_text_fallbacks(result)
+        tracer = result.tracer
+        return if tracer.nil?
+
+        if tracer.empty?
+          @out.puts("fallbacks: none")
+        else
+          @out.puts("fallbacks (#{tracer.size}):")
+          tracer.each { |event| @out.puts("  - #{format_fallback_text(event, result.file)}") }
+        end
+      end
+
+      def render_json(result)
+        payload = {
+          file: result.file,
+          line: result.line,
+          column: result.column,
+          node: result.node.class.name,
+          type: result.type.describe,
+          erased: result.type.erase_to_rbs
+        }
+        payload[:fallbacks] = result.tracer.map { |event| fallback_to_h(event) } if result.tracer
+        @out.puts(JSON.pretty_generate(payload))
+      end
+
+      def format_fallback_text(event, file)
+        "#{event.node_class} (#{event.family}) @ #{location_text(event.location, file)}"
+      end
+
+      def location_text(location, file)
+        return "<no location>" unless location.respond_to?(:start_line)
+
+        "#{file}:#{location.start_line}:#{location.start_column + 1}"
+      end
+
+      def fallback_to_h(event)
+        hash = {
+          node_class: event.node_class.name,
+          family: event.family,
+          inner_type: event.inner_type.describe
+        }
+        location = event.location
+        if location.respond_to?(:start_line)
+          hash[:line] = location.start_line
+          hash[:column] = location.start_column + 1
+        end
+        hash
+      end
+    end
+  end
+end

data/lib/rigor/cli/type_scan_command.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "optionparser"
+require "prism"
+
+require_relative "../environment"
+require_relative "../inference/coverage_scanner"
+require_relative "../scope"
+require_relative "type_scan_renderer"
+require_relative "type_scan_report"
+
+module Rigor
+  class CLI
+    # Executes the `rigor type-scan` command.
+    #
+    # The command walks every Prism node in one or more files, runs
+    # `Rigor::Scope#type_of` on each, and reports per-node-class coverage of
+    # the inference engine's directly recognized classes. It is the project's
+    # primary CI gate for tracking how much of an input source the engine can
+    # name without falling back to `Dynamic[Top]`.
+    class TypeScanCommand
+      USAGE = "Usage: rigor type-scan [options] PATH..."
+
+      LocatedEvent = Data.define(:file, :event)
+
+      def initialize(argv:, out:, err:)
+        @argv = argv
+        @out = out
+        @err = err
+      end
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        paths = collect_paths(@argv)
+        return CLI::EXIT_USAGE if paths.nil?
+        return usage_error if paths.empty?
+
+        report = scan_paths(paths, options)
+        TypeScanRenderer.new(out: @out).render(report, format: options.fetch(:format))
+        determine_exit(report, options)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", limit: 10, show_recognized: false, threshold: nil }
+
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text or json") { |value| options[:format] = value }
+          opts.on("--limit=N", Integer, "Max example events to print (text only)") do |value|
+            options[:limit] = value
+          end
+          opts.on("--show-recognized", "Include classes with 0 unrecognized in the table") do
+            options[:show_recognized] = true
+          end
+          opts.on("--threshold=RATIO", Float, "Exit non-zero when unrecognized/visits > RATIO") do |value|
+            options[:threshold] = value
+          end
+        end
+        parser.parse!(@argv)
+
+        options
+      end
+
+      def collect_paths(args)
+        paths = []
+        args.each do |arg|
+          if File.directory?(arg)
+            paths.concat(Dir.glob(File.join(arg, "**/*.rb")))
+          elsif File.file?(arg)
+            paths << arg
+          else
+            @err.puts("type-scan: not a file or directory: #{arg}")
+            return nil
+          end
+        end
+        paths.uniq
+      end
+
+      def usage_error
+        @err.puts("type-scan: at least one path is required")
+        @err.puts(USAGE)
+        CLI::EXIT_USAGE
+      end
+
+      def scan_paths(paths, options)
+        scope = Scope.empty(environment: project_environment)
+        scanner = Inference::CoverageScanner.new(scope: scope)
+        accumulator = ScanAccumulator.new
+        paths.each { |path| scan_one(path, scanner, accumulator) }
+        accumulator.to_report(paths, options)
+      end
+
+      # Builds a project-aware environment that auto-detects `<cwd>/sig`
+      # so calls scoped to the current project resolve through the
+      # local RBS tree. Phase 2a does not yet wire stdlib opt-in here;
+      # that lands when the configuration layer (`.rigor.yml`) gains an
+      # `rbs:` section.
+      def project_environment
+        Environment.for_project
+      end
+
+      def scan_one(path, scanner, accumulator)
+        source = File.read(path)
+        parse_result = Prism.parse(source, filepath: path)
+        if parse_result.errors.any?
+          accumulator.record_parse_error(path, parse_result.errors)
+          return
+        end
+
+        accumulator.absorb(path, scanner.scan(parse_result.value))
+      end
+
+      def determine_exit(report, options)
+        return 1 unless report.parse_errors.empty?
+
+        threshold = options[:threshold]
+        return 0 if threshold.nil?
+
+        report.unrecognized_ratio > threshold ? 1 : 0
+      end
+
+      # Internal helper that accumulates per-file scan results into the
+      # totals carried by `Report`.
+      class ScanAccumulator
+        def initialize
+          @visits = Hash.new(0)
+          @unrecognized = Hash.new(0)
+          @events = []
+          @parse_errors = []
+        end
+
+        def absorb(path, file_result)
+          file_result.visits.each { |klass, count| @visits[klass] += count }
+          file_result.unrecognized.each { |klass, count| @unrecognized[klass] += count }
+          file_result.events.each do |event|
+            @events << LocatedEvent.new(file: path, event: event)
+          end
+        end
+
+        def record_parse_error(path, errors)
+          @parse_errors << { file: path, errors: errors.map(&:message) }
+        end
+
+        def to_report(paths, options)
+          Report.new(
+            files: paths,
+            parse_errors: @parse_errors,
+            visits: @visits,
+            unrecognized: @unrecognized,
+            events: @events,
+            options: options
+          )
+        end
+      end
+    end
+  end
+end