fiber_audit 0.1.0

data/lib/fiber_audit/cli.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require_relative 'version'
+require_relative 'errors'
+require_relative 'configuration'
+require_relative 'project'
+require_relative 'audit'
+require_relative 'findings/severity'
+require_relative 'reporters/text'
+require_relative 'reporters/json'
+require_relative 'static/rules/built_ins'
+
+module FiberAudit
+  # rubocop:disable Metrics/ModuleLength
+  module CLI
+    module_function
+
+    def start(argv, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
+      args = argv.dup
+      command = args.shift
+
+      case command
+      when 'static'
+        run_static(args, stdout: stdout, stderr: stderr, cwd: cwd)
+      when 'list-rules'
+        reject_arguments!(args)
+        list_rules(stdout)
+      when 'explain'
+        explain_rule(args, stdout: stdout, stderr: stderr)
+      when 'version', '--version', '-v'
+        reject_arguments!(args)
+        stdout.puts "fiber-audit #{FiberAudit::VERSION}"
+        0
+      when nil
+        print_help(stdout)
+        0
+      when 'help', '--help', '-h'
+        reject_arguments!(args)
+        print_help(stdout)
+        0
+      else
+        raise OptionParser::InvalidArgument, "unknown command: #{command}"
+      end
+    rescue StandardError => e
+      stderr.puts "fiber-audit: #{e.message}"
+      2
+    end
+
+    def print_help(output = $stdout)
+      output.puts <<~HELP
+        Usage: fiber-audit <command> [options]
+
+        Commands:
+          static       Run static fiber-compatibility analysis
+          list-rules   List all registered static rules
+          explain ID   Explain a specific rule
+          version      Print version
+          help         Show this help
+
+        Run `fiber-audit static --help` for analysis options.
+      HELP
+    end
+
+    def run_static(argv, stdout:, stderr:, cwd:)
+      options, parser = parse_static_options(argv)
+      if options[:help]
+        stdout.puts parser
+        return 0
+      end
+
+      configuration, result = analyze_project(options, cwd, stderr)
+      format = options[:format] || default_format(stdout, options[:out])
+      report = render_report(format, result, color: color_enabled?(stdout, options))
+      publish_report(report, options[:out], stdout, cwd)
+
+      reportable_findings?(result.findings, configuration.min_severity) ? 1 : 0
+    end
+
+    def analyze_project(options, cwd, stderr)
+      project = Project.detect(start_path: cwd)
+      stderr.puts unknown_project_note(project) unless project.known?
+
+      config_path = project.config_path(options[:config])
+      if options[:config] && !File.file?(config_path)
+        raise ConfigurationError, "configuration file does not exist: #{config_path}"
+      end
+
+      configuration = Configuration.load(config_path)
+      configuration = with_min_severity(configuration, options[:min_severity]) if options[:min_severity]
+      result = Audit.new(configuration: configuration, root: project.root).call
+      [configuration, result]
+    end
+
+    def parse_static_options(argv)
+      options = { format: nil, config: nil, out: nil, min_severity: nil, no_color: false, help: false }
+      parser = OptionParser.new do |opts|
+        opts.banner = 'Usage: fiber-audit static [options]'
+        opts.on('--format FORMAT', %w[text json], 'Output format: text or json') { |value| options[:format] = value }
+        opts.on('--config PATH', 'Path to configuration file') { |value| options[:config] = value }
+        opts.on('--out PATH', 'Write report to a file') { |value| options[:out] = value }
+        opts.on('--min-severity SEVERITY', Severity::LEVELS.map(&:to_s), 'Minimum reported severity') do |value|
+          options[:min_severity] = value.to_sym
+        end
+        opts.on('--no-color', 'Disable ANSI colors') { options[:no_color] = true }
+        opts.on('-h', '--help', 'Show static options') { options[:help] = true }
+      end
+      parser.parse!(argv)
+      reject_arguments!(argv)
+      [options, parser]
+    end
+
+    def with_min_severity(configuration, severity)
+      Configuration.new(
+        static_include: configuration.static_include,
+        static_exclude: configuration.static_exclude,
+        rules_config: configuration.rules_config,
+        report_formats: configuration.report_formats,
+        min_severity: severity,
+        suppressions_path: configuration.suppressions_path
+      )
+    end
+
+    def default_format(stdout, output_path)
+      return 'json' if output_path
+
+      stdout.respond_to?(:tty?) && stdout.tty? ? 'text' : 'json'
+    end
+
+    def color_enabled?(stdout, options)
+      !options[:no_color] && !options[:out] && stdout.respond_to?(:tty?) && stdout.tty?
+    end
+
+    def render_report(format, result, color:)
+      case format
+      when 'text'
+        Reporters::Text.new(color: color).render(result)
+      when 'json'
+        Reporters::JSON.new(pretty: true).render(result)
+      else
+        raise OptionParser::InvalidArgument, "unsupported format: #{format}"
+      end
+    end
+
+    def publish_report(report, output_path, stdout, cwd)
+      unless output_path
+        stdout.write(report)
+        return
+      end
+
+      resolved_path = File.expand_path(output_path, cwd)
+      File.write(resolved_path, report)
+      stdout.puts "Report written to #{output_path}"
+    end
+
+    def reportable_findings?(findings, minimum)
+      findings.any? do |finding|
+        Severity.index(finding.severity) <= Severity.index(minimum)
+      end
+    end
+
+    def list_rules(stdout)
+      Static::Rules::BuiltIns.registry.each do |rule_class|
+        stdout.puts format('%<id>-7s %<severity>-8s %<description>s',
+                           id: rule_class.id,
+                           severity: rule_class.default_severity.to_s.upcase,
+                           description: rule_class.description)
+      end
+      0
+    end
+
+    def explain_rule(argv, stdout:, stderr:)
+      rule_id = argv.shift
+      reject_arguments!(argv)
+      unless rule_id
+        stderr.puts 'Usage: fiber-audit explain <RULE_ID>'
+        return 2
+      end
+
+      rule_class = Static::Rules::BuiltIns.registry.find(rule_id)
+      unless rule_class
+        stderr.puts "Unknown rule: #{rule_id}"
+        return 2
+      end
+
+      stdout.puts "#{rule_class.id} — #{rule_title(rule_class)}"
+      stdout.puts "Default severity: #{rule_class.default_severity}"
+      stdout.puts "Default confidence: #{rule_class.default_confidence}"
+      stdout.puts "Description: #{rule_class.description}"
+      stdout.puts 'Targets:'
+      rule_targets(rule_class).each { |target| stdout.puts "  - #{target}" }
+      stdout.puts "Remediation: #{rule_class.const_get(:REMEDIATION)}"
+      0
+    end
+
+    def rule_title(rule_class)
+      return 'Blocking subprocess call' if rule_class.id == 'FA1001'
+
+      %i[TITLE RULE_TITLE].each do |name|
+        return rule_class.const_get(name) if rule_class.const_defined?(name, false)
+      end
+      rule_class.name.split('::').last
+    end
+
+    def rule_targets(rule_class)
+      case rule_class.id
+      when 'FA1001'
+        expand_target_map(rule_class::TARGETS, '.')
+      when 'FA1002'
+        rule_class::TARGET_METHODS.map { |method| "Thread##{method}" }
+      when 'FA1003'
+        expand_target_map(rule_class::TARGETS, '#')
+      when 'FA1004'
+        rule_class::THREAD_VARIABLE_METHODS.map { |method| "Thread##{method}" } +
+          rule_class::INDEX_METHODS.map { |method| "Thread.current.#{method}" }
+      when 'FA1005'
+        expand_target_map(rule_class::TARGETS.transform_values { |method| [method] }, '.')
+      when 'FA1006'
+        rule_class::EXACT.map { |constant| "#{constant}.new" } + ['IPSocket subclasses']
+      when 'FA1007'
+        rule_class::NET_HTTP_METHODS.map { |method| "Net::HTTP.#{method}" } +
+          rule_class::URI_METHODS.map { |constant, method| "#{constant}.#{method}" }
+      else
+        []
+      end
+    end
+
+    def expand_target_map(targets, separator)
+      targets.flat_map do |constant, methods|
+        Array(methods).map { |method| "#{constant}#{separator}#{method}" }
+      end
+    end
+
+    def reject_arguments!(argv)
+      return if argv.empty?
+
+      raise OptionParser::InvalidArgument, "unexpected arguments: #{argv.join(' ')}"
+    end
+
+    def unknown_project_note(project)
+      "Note: project root could not be detected; using #{project.root}"
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/fiber_audit/configuration.rb

@@ -0,0 +1,236 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'pathname'
+require_relative 'errors'
+require_relative 'findings/severity'
+
+module FiberAudit
+  class Configuration
+    KNOWN_TOP_LEVEL_KEYS = %w[static rules report].freeze
+    KNOWN_STATIC_KEYS = %w[include exclude suppressions_path].freeze
+    KNOWN_REPORT_KEYS = %w[formats min_severity].freeze
+    KNOWN_RULE_KEYS = %w[enabled severity].freeze
+    VALID_FORMATS = %w[text json].freeze
+
+    DEFAULT_STATIC_INCLUDE = %w[
+      app/**/*.rb
+      lib/**/*.rb
+      config/**/*.rb
+      config/initializers/**/*.rb
+    ].freeze
+
+    DEFAULT_STATIC_EXCLUDE = %w[
+      vendor/**/*
+      tmp/**/*
+      node_modules/**/*
+      db/schema.rb
+    ].freeze
+
+    attr_reader :static_include, :static_exclude, :rules_config,
+                :report_formats, :min_severity, :suppressions_path
+
+    def initialize(
+      static_include: DEFAULT_STATIC_INCLUDE,
+      static_exclude: DEFAULT_STATIC_EXCLUDE,
+      rules_config: {},
+      report_formats: %w[text],
+      min_severity: :low,
+      suppressions_path: nil
+    )
+      validate_types!(
+        static_include, static_exclude, rules_config,
+        report_formats, min_severity, suppressions_path
+      )
+
+      @static_include = static_include
+      @static_exclude = static_exclude
+      @rules_config = rules_config
+      @report_formats = report_formats
+      @min_severity = coerce_severity(min_severity, 'report.min_severity')
+      @suppressions_path = suppressions_path
+    end
+
+    def rule_enabled?(rule_id)
+      entry = @rules_config[rule_id] || {}
+      entry.fetch('enabled', true)
+    end
+
+    # Returns the overridden severity for a rule as a validated Symbol,
+    # or nil when no override is configured.
+    def severity_override(rule_id)
+      entry = @rules_config[rule_id] || {}
+      sev = entry['severity']
+      return nil unless sev
+
+      coerce_severity(sev, "rules.#{rule_id}.severity")
+    end
+
+    class << self
+      def load(path = nil)
+        return new unless path && File.exist?(path)
+
+        yaml = YAML.safe_load_file(path) || {}
+        validate_yaml_structure!(yaml)
+
+        static = yaml['static'] || {}
+        rules = yaml['rules'] || {}
+        report = yaml['report'] || {}
+
+        new(
+          static_include: static['include'] || DEFAULT_STATIC_INCLUDE,
+          static_exclude: static['exclude'] || DEFAULT_STATIC_EXCLUDE,
+          rules_config: rules,
+          report_formats: report['formats'] || %w[text],
+          min_severity: report.fetch('min_severity', :low),
+          suppressions_path: static['suppressions_path']
+        )
+      end
+
+      private
+
+      def validate_yaml_structure!(yaml)
+        unless yaml.is_a?(Hash)
+          raise ConfigurationError,
+                "configuration must be a YAML mapping, got #{yaml.class}"
+        end
+
+        check_unknown_keys(yaml, KNOWN_TOP_LEVEL_KEYS, 'top level')
+
+        if yaml.key?('static')
+          static = yaml['static']
+          unless static.is_a?(Hash)
+            raise ConfigurationError,
+                  "static must be a mapping, got #{static.class}"
+          end
+          check_unknown_keys(static, KNOWN_STATIC_KEYS, 'static')
+        end
+
+        if yaml.key?('report')
+          report = yaml['report']
+          unless report.is_a?(Hash)
+            raise ConfigurationError,
+                  "report must be a mapping, got #{report.class}"
+          end
+          check_unknown_keys(report, KNOWN_REPORT_KEYS, 'report')
+        end
+
+        return unless yaml.key?('rules')
+
+        rules = yaml['rules']
+        return if rules.is_a?(Hash)
+
+        raise ConfigurationError,
+              "rules must be a mapping, got #{rules.class}"
+      end
+
+      def check_unknown_keys(hash, allowed, path)
+        unknown = hash.keys - allowed
+        return if unknown.empty?
+
+        sorted_allowed = allowed.sort.join(', ')
+        raise ConfigurationError,
+              "unknown configuration key '#{unknown.first}' at #{path} " \
+              "(valid keys: #{sorted_allowed})"
+      end
+    end
+
+    private
+
+    def validate_types!(
+      include_patterns, exclude_patterns, rules,
+      formats, _severity, suppressions
+    )
+      unless include_patterns.is_a?(Array) &&
+             include_patterns.all?(String)
+        raise ConfigurationError,
+              'static.include must be an Array of Strings'
+      end
+
+      unless exclude_patterns.is_a?(Array) &&
+             exclude_patterns.all?(String)
+        raise ConfigurationError,
+              'static.exclude must be an Array of Strings'
+      end
+
+      raise ConfigurationError, 'rules must be a Hash' unless rules.is_a?(Hash)
+
+      validate_rules!(rules)
+      validate_report_formats!(formats)
+
+      return if suppressions.nil? || suppressions.is_a?(String)
+
+      raise ConfigurationError,
+            'static.suppressions_path must be nil or a String'
+    end
+
+    def validate_report_formats!(formats)
+      unless formats.is_a?(Array)
+        raise ConfigurationError,
+              'report.formats must be an Array'
+      end
+
+      if formats.empty?
+        raise ConfigurationError,
+              'report.formats must not be empty'
+      end
+
+      invalid = formats.reject { |f| VALID_FORMATS.include?(f) }
+      return if invalid.empty?
+
+      raise ConfigurationError,
+            "report.formats contains invalid: #{invalid.inspect} " \
+            '(valid formats: text, json)'
+    end
+
+    def validate_rules!(rules)
+      rules.each do |rule_id, entry|
+        unless entry.is_a?(Hash)
+          raise ConfigurationError,
+                "rules.#{rule_id} must be a Hash, got #{entry.class}"
+        end
+
+        unknown = entry.keys - KNOWN_RULE_KEYS
+        unless unknown.empty?
+          sorted_allowed = KNOWN_RULE_KEYS.sort.join(', ')
+          raise ConfigurationError,
+                "unknown configuration key '#{unknown.first}' " \
+                "in rules.#{rule_id} " \
+                "(valid keys: #{sorted_allowed})"
+        end
+
+        if entry.key?('enabled') &&
+           ![true, false].include?(entry['enabled'])
+          raise ConfigurationError,
+                "rules.#{rule_id}.enabled must be a Boolean"
+        end
+
+        next unless entry.key?('severity')
+
+        coerce_severity(
+          entry['severity'], "rules.#{rule_id}.severity"
+        )
+      end
+    end
+
+    # Centralized severity coercion.
+    # Normalizes String to Symbol before delegating to Severity.coerce.
+    # Raises path-anchored ConfigurationError for invalid types or values.
+    def coerce_severity(value, path)
+      normalized = case value
+                   when Symbol
+                     value
+                   when String
+                     value.to_sym
+                   else
+                     raise ConfigurationError,
+                           "#{path} must be a String or Symbol, " \
+                           "got #{value.class}"
+                   end
+      Severity.coerce(normalized)
+    rescue ArgumentError
+      raise ConfigurationError,
+            "#{path} is not a valid severity: #{value.inspect}"
+    end
+  end
+end

data/lib/fiber_audit/correlation/fingerprint.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'pathname'
+
+module FiberAudit
+  module Correlation
+    module Fingerprint
+      module_function
+
+      def call(rule_id:, path:, enclosing_symbol:, operation:)
+        Digest::SHA256.hexdigest(
+          [rule_id, normalize_path(path), enclosing_symbol, operation].join(':')
+        )
+      end
+
+      def normalize_path(path)
+        return '' if path.nil?
+
+        Pathname.new(path).cleanpath.to_s
+      rescue ArgumentError
+        path.to_s
+      end
+    end
+  end
+end

data/lib/fiber_audit/errors.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  class ConfigurationError < StandardError; end
+  class EmptyEvidenceError < StandardError; end
+  class ReporterError < StandardError; end
+  class ProjectError < StandardError; end
+end

data/lib/fiber_audit/execution_context.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  # Execution context constants for classifying where code runs.
+  #
+  # These contexts represent the execution environment of a call site:
+  # - request: ActionController handling an HTTP request
+  # - middleware: Rack middleware in the request chain
+  # - callback: ActiveRecord/ActiveSupport callback
+  # - view: ActionView template rendering
+  # - job: ActiveJob background job
+  # - websocket: ActionCable WebSocket handler
+  # - boot: Rails initializer or boot sequence
+  # - console: Rails console or IRB session
+  # - rake_task: Rake task execution
+  # - test: Test suite (RSpec, Minitest)
+  # - unknown: Cannot determine context
+  #
+  # The ALL array is frozen and ordered for iteration.
+  module Context
+    REQUEST    = :request
+    MIDDLEWARE = :middleware
+    CALLBACK   = :callback
+    VIEW       = :view
+    JOB        = :job
+    WEBSOCKET  = :websocket
+    BOOT       = :boot
+    CONSOLE    = :console
+    RAKE_TASK  = :rake_task
+    TEST       = :test
+    UNKNOWN    = :unknown
+
+    ALL = [
+      REQUEST,
+      MIDDLEWARE,
+      CALLBACK,
+      VIEW,
+      JOB,
+      WEBSOCKET,
+      BOOT,
+      CONSOLE,
+      RAKE_TASK,
+      TEST,
+      UNKNOWN
+    ].freeze
+  end
+end

data/lib/fiber_audit/findings/collection.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative '../errors'
+
+module FiberAudit
+  class Collection
+    include Enumerable
+
+    def initialize(findings = [])
+      @findings = Array(findings).dup
+      @findings.each { |f| validate_evidence!(f) }
+    end
+
+    def each(&)
+      @findings.each(&)
+    end
+
+    def add(finding)
+      validate_evidence!(finding)
+      @findings << finding
+      self
+    end
+
+    def by_rule(rule_id)
+      @findings.select { _1.rule_id == rule_id }
+    end
+
+    def by_severity_min(min_severity)
+      min_index = Severity.index(min_severity)
+      @findings.select { Severity.index(_1.severity) <= min_index }
+    end
+
+    def size
+      @findings.size
+    end
+
+    def empty?
+      @findings.empty?
+    end
+
+    def to_a
+      @findings.dup
+    end
+
+    def to_h_for_json
+      @findings.map(&:to_h_for_json)
+    end
+
+    private
+
+    def validate_evidence!(finding)
+      return if finding.evidence&.any?
+
+      raise EmptyEvidenceError,
+            "Finding #{finding.rule_id} (#{finding.fingerprint[0, 8]}) cannot be published without evidence"
+    end
+  end
+end

data/lib/fiber_audit/findings/confidence.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  module Confidence
+    LEVELS = %i[confirmed high medium low unknown].freeze
+
+    module_function
+
+    def coerce(value)
+      return value if LEVELS.include?(value)
+
+      raise ArgumentError, "unknown confidence: #{value.inspect}"
+    end
+
+    def index(confidence)
+      LEVELS.index(confidence) || LEVELS.size
+    end
+  end
+end

data/lib/fiber_audit/findings/evidence.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  Evidence = Data.define(:source, :message, :details) do
+    def initialize(source:, message:, details: {})
+      super(source: source, message: message, details: details || {})
+    end
+
+    def to_h_for_json
+      { source: source, message: message, details: details }
+    end
+  end
+end