rigortype 0.1.17 → 0.1.18

data/lib/rigor/cli/ci_detector.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Rigor
+  class CLI
+    # Runtime CI-environment detection (ADR-51 WD7), modelled on
+    # `OndraM/ci-detector` (the library PHPStan uses). Reads the well-known
+    # environment variables a CI provider sets and returns the matching
+    # {Platform}, classifying it into a **tier** that decides how
+    # `rigor check` surfaces diagnostics there:
+    #
+    #   :native_stdout   — Rigor has a native format that renders purely from
+    #                      stdout, so it is auto-emitted on top of the human
+    #                      output (GitHub Actions → `github`, TeamCity →
+    #                      `teamcity`). These are the first-class platforms.
+    #   :native_artifact — Rigor has a native format but it needs a CI-wired
+    #                      report artifact, not stdout (GitLab CI → `gitlab`).
+    #                      First-class, but Rigor only *hints* the format.
+    #   :reviewdog       — no native Rigor format; second-class, routed through
+    #                      reviewdog (`checkstyle`/`sarif`) or `junit`. Hint
+    #                      only.
+    #
+    # Detection is a pure function of the environment hash, so it is fully
+    # testable; the CLI passes `ENV`. `RIGOR_CI_DETECT=0` (or `false`/`no`)
+    # disables it globally — the seam the spec suite uses for determinism.
+    module CiDetector
+      Platform = Struct.new(:id, :name, :format, :tier, keyword_init: true) do
+        def native_stdout? = tier == :native_stdout
+        def native_artifact? = tier == :native_artifact
+        def reviewdog? = tier == :reviewdog
+      end
+
+      # The detection table, ordered most-specific first so the generic
+      # `CI=true` catch-all is last (a provider that also sets `CI` is still
+      # recognised by its own variable). `match` is `:truthy` (value in
+      # 1/true/yes/on), `:present` (variable set non-empty), or `:equals`.
+      PROVIDERS = [
+        { id: "github-actions", name: "GitHub Actions", format: "github", tier: :native_stdout,
+          var: "GITHUB_ACTIONS", match: :truthy },
+        { id: "gitlab", name: "GitLab CI", format: "gitlab", tier: :native_artifact,
+          var: "GITLAB_CI", match: :truthy },
+        { id: "teamcity", name: "TeamCity", format: "teamcity", tier: :native_stdout,
+          var: "TEAMCITY_VERSION", match: :present },
+        { id: "circleci", name: "CircleCI", format: nil, tier: :reviewdog,
+          var: "CIRCLECI", match: :truthy },
+        { id: "jenkins", name: "Jenkins", format: nil, tier: :reviewdog,
+          var: "JENKINS_URL", match: :present },
+        { id: "travis", name: "Travis CI", format: nil, tier: :reviewdog,
+          var: "TRAVIS", match: :truthy },
+        { id: "appveyor", name: "AppVeyor", format: nil, tier: :reviewdog,
+          var: "APPVEYOR", match: :truthy },
+        { id: "azure-pipelines", name: "Azure Pipelines", format: nil, tier: :reviewdog,
+          var: "TF_BUILD", match: :present },
+        { id: "bitbucket", name: "Bitbucket Pipelines", format: nil, tier: :reviewdog,
+          var: "BITBUCKET_BUILD_NUMBER", match: :present },
+        { id: "buildkite", name: "Buildkite", format: nil, tier: :reviewdog,
+          var: "BUILDKITE", match: :truthy },
+        { id: "drone", name: "Drone CI", format: nil, tier: :reviewdog,
+          var: "DRONE", match: :truthy },
+        { id: "semaphore", name: "Semaphore", format: nil, tier: :reviewdog,
+          var: "SEMAPHORE", match: :truthy },
+        { id: "codeship", name: "Codeship", format: nil, tier: :reviewdog,
+          var: "CI_NAME", match: :equals, value: "codeship" },
+        { id: "ci", name: "CI", format: nil, tier: :reviewdog,
+          var: "CI", match: :truthy }
+      ].freeze
+
+      module_function
+
+      # Returns the detected {Platform}, or nil when no CI is recognised or
+      # detection is disabled via `RIGOR_CI_DETECT`.
+      def detect(env = ENV)
+        return nil if disabled?(env)
+
+        row = PROVIDERS.find { |provider| matches?(env, provider) }
+        return nil if row.nil?
+
+        Platform.new(id: row[:id], name: row[:name], format: row[:format], tier: row[:tier])
+      end
+
+      def disabled?(env)
+        %w[0 false no off].include?(env["RIGOR_CI_DETECT"].to_s.strip.downcase)
+      end
+
+      def matches?(env, provider)
+        value = env[provider[:var]].to_s.strip
+        case provider[:match]
+        when :truthy then %w[1 true yes on].include?(value.downcase)
+        when :present then !value.empty?
+        when :equals then value.downcase == provider[:value]
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/diagnostic_formats.rb

@@ -0,0 +1,345 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "../version"
+
+module Rigor
+  class CLI
+    # CI-native diagnostic output formats (ADR-51). Each renders an
+    # `Analysis::Result` to a string a CI platform consumes to surface
+    # diagnostics inline in a pull / merge request, rather than only in the
+    # job log. They read the same `Diagnostic` fields as `--format json`
+    # (path / line / column / severity / qualified rule / message) and add
+    # no new information — only a platform-native rendering of it.
+    #
+    #   sarif      — SARIF 2.1.0 (cross-platform; GitHub code-scanning, any
+    #                other SARIF tool, and reviewdog `-f=sarif`)
+    #   github     — GitHub Actions workflow commands (`::error file=…,line=…::`)
+    #                that the runner turns into inline PR annotations
+    #   gitlab     — GitLab Code Quality report JSON (the CodeClimate subset)
+    #                that drives the merge-request Code Quality widget
+    #   checkstyle — Checkstyle XML, the broad lint-interchange format that
+    #                reviewdog (`-f=checkstyle`) and Jenkins/etc. consume
+    #   junit      — JUnit XML, the test-report format many CI systems render
+    #
+    # Severity maps once per format from Rigor's `:error` / `:warning` /
+    # `:info`; the qualified rule (`<source_family>.<rule>` or the bare rule
+    # for the builtin family) is the stable identifier, nil only for the
+    # ruleless producers (parse / internal errors), which each format
+    # degrades gracefully.
+    module DiagnosticFormats
+      FORMATS = %w[sarif github gitlab checkstyle junit teamcity].freeze
+
+      module_function
+
+      def supports?(format)
+        FORMATS.include?(format)
+      end
+
+      # Renders `result` in the named CI format. Callers gate on
+      # {.supports?} first; an unrecognised format returns nil.
+      def render(result, format)
+        case format
+        when "sarif" then Sarif.new(result).render
+        when "github" then GithubActions.new(result).render
+        when "gitlab" then GitlabCodeQuality.new(result).render
+        when "checkstyle" then Checkstyle.new(result).render
+        when "junit" then Junit.new(result).render
+        when "teamcity" then Teamcity.new(result).render
+        end
+      end
+
+      # XML attribute / text escaping shared by the Checkstyle and JUnit
+      # formatters. Covers the five predefined XML entities so a diagnostic
+      # message carrying `<`, `&`, or a quote can't break the document.
+      module XmlEscaping
+        ENTITIES = { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;",
+                     '"' => "&quot;", "'" => "&apos;" }.freeze
+
+        def xml_escape(value)
+          value.to_s.gsub(/[&<>"']/, ENTITIES)
+        end
+      end
+
+      # SARIF 2.1.0 — the OASIS static-analysis interchange format. GitHub's
+      # `codeql-action/upload-sarif` ingests it to render findings on the PR
+      # diff and in the Security tab; it is the cross-platform anchor format.
+      class Sarif
+        SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+        INFORMATION_URI = "https://github.com/rigortype/rigor"
+
+        # SARIF defines exactly three result levels; Rigor's `:info` is a
+        # `note` (the SARIF spelling for advisory findings).
+        LEVELS = { error: "error", warning: "warning", info: "note" }.freeze
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          JSON.pretty_generate(document)
+        end
+
+        private
+
+        def document
+          { "version" => "2.1.0", "$schema" => SCHEMA, "runs" => [run] }
+        end
+
+        def run
+          {
+            "tool" => { "driver" => driver },
+            "results" => @result.diagnostics.map { |diagnostic| result_for(diagnostic) }
+          }
+        end
+
+        def driver
+          {
+            "name" => "Rigor",
+            "informationUri" => INFORMATION_URI,
+            "version" => Rigor::VERSION,
+            "rules" => rules
+          }
+        end
+
+        # The distinct rule ids seen in this run, declared so consumers can
+        # cross-reference each result's `ruleId`. Id-only is a valid minimal
+        # SARIF rule object; richer per-rule metadata is a later enrichment.
+        def rules
+          @result.diagnostics.filter_map(&:qualified_rule).uniq.map { |id| { "id" => id } }
+        end
+
+        def result_for(diagnostic)
+          entry = {
+            "level" => LEVELS.fetch(diagnostic.severity, "warning"),
+            "message" => { "text" => diagnostic.message },
+            "locations" => [location_for(diagnostic)]
+          }
+          rule_id = diagnostic.qualified_rule
+          entry["ruleId"] = rule_id if rule_id
+          entry
+        end
+
+        # Rigor lines / columns are already 1-based, matching SARIF's
+        # 1-based `startLine` / `startColumn`. Paths are project-relative;
+        # SARIF URIs use forward slashes on every platform.
+        def location_for(diagnostic)
+          {
+            "physicalLocation" => {
+              "artifactLocation" => { "uri" => diagnostic.path.to_s.tr("\\", "/") },
+              "region" => { "startLine" => diagnostic.line, "startColumn" => diagnostic.column }
+            }
+          }
+        end
+      end
+
+      # GitHub Actions workflow commands — `::<level> file=…,line=…,col=…,
+      # title=…::<message>` lines the runner parses out of stdout and turns
+      # into inline PR annotations, with no separate upload step.
+      class GithubActions
+        # GitHub's annotation levels; Rigor's `:info` is a `notice`.
+        LEVELS = { error: "error", warning: "warning", info: "notice" }.freeze
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          @result.diagnostics.map { |diagnostic| line_for(diagnostic) }.join("\n")
+        end
+
+        private
+
+        def line_for(diagnostic)
+          level = LEVELS.fetch(diagnostic.severity, "warning")
+          props = ["file=#{escape_property(diagnostic.path)}",
+                   "line=#{diagnostic.line}", "col=#{diagnostic.column}"]
+          rule_id = diagnostic.qualified_rule
+          props << "title=#{escape_property(rule_id)}" if rule_id
+          "::#{level} #{props.join(',')}::#{escape_data(diagnostic.message)}"
+        end
+
+        # GitHub's documented workflow-command escaping: `%` and the CR / LF
+        # that would otherwise terminate the command line, for message data.
+        def escape_data(value)
+          value.to_s.gsub("%", "%25").gsub("\r", "%0D").gsub("\n", "%0A")
+        end
+
+        # Property values additionally escape the `,` (property separator)
+        # and `:` (command terminator) so a path or rule id can carry them.
+        def escape_property(value)
+          escape_data(value).gsub(",", "%2C").gsub(":", "%3A")
+        end
+      end
+
+      # GitLab Code Quality report — the CodeClimate-subset JSON array GitLab
+      # reads from a `codequality` CI artifact to populate the merge-request
+      # Code Quality widget.
+      class GitlabCodeQuality
+        # GitLab's severity vocabulary (a CodeClimate subset). Rigor maps
+        # error → major, warning → minor, info → info; `critical` / `blocker`
+        # are left for a louder future tier.
+        SEVERITIES = { error: "major", warning: "minor", info: "info" }.freeze
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          JSON.pretty_generate(@result.diagnostics.map { |diagnostic| entry_for(diagnostic) })
+        end
+
+        private
+
+        def entry_for(diagnostic)
+          {
+            "description" => description(diagnostic),
+            "check_name" => diagnostic.qualified_rule || "rigor",
+            "fingerprint" => fingerprint(diagnostic),
+            "severity" => SEVERITIES.fetch(diagnostic.severity, "minor"),
+            "location" => {
+              "path" => diagnostic.path.to_s,
+              "lines" => { "begin" => diagnostic.line }
+            }
+          }
+        end
+
+        # The rule id is folded into the description (the widget shows it)
+        # because Code Quality has no dedicated rule field.
+        def description(diagnostic)
+          rule_id = diagnostic.qualified_rule
+          rule_id ? "#{diagnostic.message} [#{rule_id}]" : diagnostic.message
+        end
+
+        # GitLab dedups findings by fingerprint and tracks them across runs
+        # by it, so it must be stable for an unchanged finding and unique per
+        # finding. Hashing the locating tuple (path, rule, line, column,
+        # message) satisfies both — order-independent, no run-volatile input.
+        def fingerprint(diagnostic)
+          payload = [diagnostic.path, diagnostic.qualified_rule, diagnostic.line,
+                     diagnostic.column, diagnostic.message].join("")
+          Digest::SHA256.hexdigest(payload)
+        end
+      end
+
+      # Checkstyle XML — the lint-interchange format a wide range of tools
+      # read, most usefully reviewdog (`-f=checkstyle`), which then posts to
+      # any of its reporters (GitHub PR review, GitLab MR, Gerrit, …). Errors
+      # are grouped by file; the qualified rule rides in `source` (the rule
+      # code reviewdog surfaces). Checkstyle's native severities are
+      # `error` / `warning` / `info`, so Rigor's map through unchanged.
+      class Checkstyle
+        include XmlEscaping
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          lines = ['<?xml version="1.0" encoding="UTF-8"?>', "<checkstyle>"]
+          @result.diagnostics.group_by(&:path).each do |path, diagnostics|
+            lines << %(  <file name="#{xml_escape(path)}">)
+            diagnostics.each { |diagnostic| lines << error_element(diagnostic) }
+            lines << "  </file>"
+          end
+          lines << "</checkstyle>"
+          lines.join("\n")
+        end
+
+        private
+
+        def error_element(diagnostic)
+          attrs = %(line="#{diagnostic.line}" column="#{diagnostic.column}" ) +
+                  %(severity="#{diagnostic.severity}" message="#{xml_escape(diagnostic.message)}")
+          rule_id = diagnostic.qualified_rule
+          attrs += %( source="#{xml_escape(rule_id)}") if rule_id
+          "    <error #{attrs} />"
+        end
+      end
+
+      # JUnit XML — the test-report format GitHub's test reporting, GitLab,
+      # Jenkins, and CircleCI render. Following the established linter
+      # convention (rubocop / eslint / PHPStan): every diagnostic is a
+      # `testcase` carrying a `failure` typed by its severity, so all of them
+      # are visible in the report. The exit code (errors only) remains the
+      # gate; this view is for surfacing, not gating.
+      class Junit
+        include XmlEscaping
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          diagnostics = @result.diagnostics
+          # JUnit wants at least one test; a clean run reports one passing case.
+          tests = diagnostics.empty? ? 1 : diagnostics.size
+          lines = ['<?xml version="1.0" encoding="UTF-8"?>',
+                   %(<testsuite name="rigor" tests="#{tests}" failures="#{diagnostics.size}">)]
+          if diagnostics.empty?
+            lines << '  <testcase name="rigor" />'
+          else
+            diagnostics.each { |diagnostic| lines.concat(testcase(diagnostic)) }
+          end
+          lines << "</testsuite>"
+          lines.join("\n")
+        end
+
+        private
+
+        def testcase(diagnostic)
+          name = "#{diagnostic.path}:#{diagnostic.line}:#{diagnostic.column}"
+          classname = diagnostic.qualified_rule || "rigor"
+          [
+            %(  <testcase name="#{xml_escape(name)}" classname="#{xml_escape(classname)}">),
+            %(    <failure type="#{diagnostic.severity}" message="#{xml_escape(diagnostic.message)}" />),
+            "  </testcase>"
+          ]
+        end
+      end
+
+      # TeamCity inspection service messages — the `##teamcity[…]` lines a
+      # TeamCity build agent parses out of the build log into its Inspections
+      # view. The one stdout-native format (besides `github`) that
+      # CI-detection auto-emits. One `inspectionType` declares the category;
+      # each diagnostic is an `inspection` typed by severity.
+      class Teamcity
+        SEVERITIES = { error: "ERROR", warning: "WARNING", info: "INFO" }.freeze
+
+        def initialize(result)
+          @result = result
+        end
+
+        def render
+          return "" if @result.diagnostics.empty?
+
+          lines = [message("inspectionType", id: "rigor", name: "rigor",
+                                             category: "rigor", description: "Rigor inspection")]
+          @result.diagnostics.each { |diagnostic| lines << inspection(diagnostic) }
+          lines.join("\n")
+        end
+
+        private
+
+        def inspection(diagnostic)
+          rule_id = diagnostic.qualified_rule
+          text = rule_id ? "#{diagnostic.message} [#{rule_id}]" : diagnostic.message
+          message("inspection", typeId: "rigor", message: text, file: diagnostic.path,
+                                line: diagnostic.line, SEVERITY: SEVERITIES.fetch(diagnostic.severity, "WARNING"))
+        end
+
+        def message(name, attrs)
+          pairs = attrs.map { |key, value| "#{key}='#{escape(value)}'" }.join(" ")
+          "##teamcity[#{name} #{pairs}]"
+        end
+
+        # TeamCity's documented service-message escaping.
+        def escape(value)
+          value.to_s.gsub("|", "||").gsub("'", "|'").gsub("\n", "|n")
+               .gsub("\r", "|r").gsub("[", "|[").gsub("]", "|]")
+        end
+      end
+    end
+  end
+end

data/lib/rigor/cli/prism_colorizer.rb

@@ -41,12 +41,19 @@ module Rigor
       # @return [String] the source with ANSI colour escapes, or
       #   the input unchanged when lexing surfaces an error.
       def colorize(source)
+        # Sources read under a POSIX locale arrive tagged US-ASCII even
+        # when they carry UTF-8 bytes; retag so the token regexes below
+        # do not raise on multibyte comments.
+        source = source.dup.force_encoding(Encoding::UTF_8) unless source.encoding == Encoding::UTF_8
         result = Prism.lex(source)
         return source unless result.errors.empty?
 
         render(source, result.value)
       end
 
+      # Prism token offsets are BYTE offsets — slice with byteslice, or
+      # any multibyte character earlier in the source shifts every
+      # subsequent token boundary.
       def render(source, lexed)
         out = +""
         offset = 0
@@ -54,15 +61,15 @@ module Rigor
         lexed.each do |entry|
           token = entry.first
           location = token.location
-          out << source[offset...location.start_offset]
+          out << (source.byteslice(offset, [location.start_offset - offset, 0].max) || "")
           break if token.type == :EOF
 
-          text = source[location.start_offset...location.end_offset]
+          text = source.byteslice(location.start_offset, location.end_offset - location.start_offset) || ""
           out << paint(text, effective_category(token.type, previous_type))
           offset = location.end_offset
           previous_type = token.type
         end
-        out << (source[offset..] || "")
+        out << (source.byteslice(offset, source.bytesize - offset) || "")
         out
       end
 

data/lib/rigor/cli/trace_command.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require "optionparser"
+require "prism"
+
+require_relative "../configuration"
+require_relative "../environment"
+require_relative "../scope"
+require_relative "../inference/flow_tracer"
+require_relative "../inference/scope_indexer"
+require_relative "command"
+require_relative "trace_renderer"
+
+module Rigor
+  class CLI
+    # Executes the `rigor trace` command: re-runs the inference engine
+    # over one file under {Rigor::Inference::FlowTracer} and replays the
+    # recorded event stream — scope binds, union formation, method
+    # dispatch, and (with `--verbose`) every expression enter/result —
+    # as a step-through terminal animation. A teaching probe: it shows
+    # HOW Rigor arrives at a type, where `rigor type-of` shows only the
+    # answer.
+    #
+    # The tracer is observational; this command never changes what
+    # `rigor check` would infer for the same file.
+    class TraceCommand < Command
+      USAGE = "Usage: rigor trace [options] FILE"
+
+      # Default frame kinds: the three teachable moments. :enter/:result
+      # add one frame per literal and drown the signal; `--verbose`
+      # opts into them.
+      DEFAULT_KINDS = %i[bind union dispatch].freeze
+      VERBOSE_KINDS = (%i[enter result] + DEFAULT_KINDS).freeze
+
+      # @return [Integer] CLI exit status.
+      def run
+        options = parse_options
+        file = @argv.first
+        if file.nil? || @argv.size != 1
+          @err.puts(USAGE)
+          return CLI::EXIT_USAGE
+        end
+        return 1 unless file_exists?(file)
+
+        execute(file: file, options: options)
+      end
+
+      private
+
+      def parse_options
+        options = { format: "text", delay: nil, verbose: false, line: nil, config: nil }
+        parser = OptionParser.new do |opts|
+          opts.banner = USAGE
+          opts.on("--format=FORMAT", "Output format: text (animation) or json (raw event stream)") do |value|
+            options[:format] = value
+          end
+          opts.on("--delay=SECONDS", Float,
+                  "Autoplay with SECONDS between frames (default: step on key press)") do |value|
+            options[:delay] = value
+          end
+          opts.on("--line=N", Integer, "Only replay events whose source range starts on line N") do |value|
+            options[:line] = value
+          end
+          opts.on("--verbose", "Include every expression enter/result frame") { options[:verbose] = true }
+          opts.on("--config=PATH", "Path to the Rigor configuration file") { |value| options[:config] = value }
+        end
+        parser.parse!(@argv)
+        options
+      end
+
+      def execute(file:, options:)
+        configuration = Configuration.load(options.fetch(:config))
+        source = File.read(file, encoding: Encoding::UTF_8)
+        parse_result = Prism.parse(source, filepath: file, version: configuration.target_ruby)
+        return 1 if parse_errors?(parse_result, file)
+
+        events = record_events(parse_result.value, file, configuration)
+        frames = filter(events, options)
+
+        if options.fetch(:format) == "json"
+          @out.puts(JSON.pretty_generate(frames.map { |event| event_to_h(event) }))
+          return 0
+        end
+
+        if frames.empty?
+          @out.puts("trace: no events to replay (try --verbose)")
+          return 0
+        end
+
+        interactive = @out.respond_to?(:tty?) && @out.tty?
+        TraceRenderer.new(out: @out, source: source, file: file)
+                     .play(frames, delay: options.fetch(:delay), interactive: interactive)
+        0
+      end
+
+      # Mirrors the single-file path `rigor type-of` takes: a
+      # project-aware environment, an empty seed scope, one
+      # statement-level evaluation of the whole program — but recorded
+      # under the FlowTracer.
+      def record_events(root, file, configuration)
+        environment = Environment.for_project(
+          libraries: configuration.libraries,
+          signature_paths: configuration.signature_paths
+        )
+        scope = Scope.empty(environment: environment, source_path: file)
+        Inference::FlowTracer.record { scope.evaluate(root) }
+      end
+
+      def filter(events, options)
+        kinds = options.fetch(:verbose) ? VERBOSE_KINDS : DEFAULT_KINDS
+        frames = events.select { |event| kinds.include?(event.kind) }
+        line = options.fetch(:line)
+        frames = frames.select { |event| event.location && event.location[:start_line] == line } if line
+        frames
+      end
+
+      def event_to_h(event)
+        {
+          kind: event.kind,
+          depth: event.depth,
+          location: event.location,
+          stack: event.stack,
+          data: event.data
+        }
+      end
+
+      def file_exists?(file)
+        return true if File.file?(file)
+
+        @err.puts("trace: 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
+    end
+  end
+end