fiber_audit 0.1.0

data/lib/fiber_audit/static/semantic_index.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+require 'pathname'
+require 'rubydex'
+
+module FiberAudit
+  module Static
+    # Semantic index backed by Rubydex 0.2.9.
+    #
+    # === Line/column conventions (FiberAudit standard)
+    # * Lines are **one-based** (1, 2, 3, ...).
+    # * Columns are **zero-based** (0, 1, 2, ...).
+    #
+    # Rubydex 0.2.9 reports start_line as **zero-based** and start_column as
+    # zero-based. The +normalize_location+ helper adds 1 to start_line so that
+    # all returned locations use FiberAudit's one-based line convention.
+    class SemanticIndex
+      # Data types returned by public seams.
+      Declaration = Data.define(:name, :kind, :path, :line)
+      Reference   = Data.define(:name, :path, :line, :column, :context)
+      Constant    = Data.define(:name, :path, :line)
+      RubydexGap  = Data.define(:method, :reason)
+
+      attr_reader :root, :gaps
+
+      def initialize(root:)
+        @root = Pathname.new(root).expand_path.cleanpath
+        @graph = nil
+        @gaps = []
+      end
+
+      # Build (or rebuild) the index. Clears and deduplicates gaps on every call.
+      def build
+        @gaps = []
+        @graph = ::Rubydex::Graph.new
+        @graph.workspace_path = @root.to_s
+        @graph.index_workspace
+        @graph.resolve
+        record_gaps
+        self
+      rescue StandardError => e
+        @gaps << RubydexGap.new(method: 'build', reason: e.message)
+        self
+      end
+
+      # Returns Array[Declaration] for classes/modules/methods in the workspace.
+      # Returns one Declaration per workspace definition site so that reopened
+      # classes expose both (or more) definition sites.
+      def declarations
+        return [] unless @graph
+
+        @graph.declarations.select { |d| workspace_declaration?(d) }.filter_map do |decl|
+          kind = declaration_kind(decl)
+          workspace_definition_locations(decl).filter_map do |loc|
+            path, line = normalize_location(loc)
+            next unless path
+
+            Declaration.new(name: decl.name, kind: kind, path: path, line: line)
+          end
+        end.flatten
+      rescue StandardError
+        []
+      end
+
+      # Resolves a constant name to a Constant object.
+      # Returns nil if the constant cannot be resolved or is outside the workspace.
+      def resolve_constant(name, nesting:)
+        return nil unless @graph
+
+        result = @graph.resolve_constant(name.to_s, nesting || [])
+        return nil unless result
+
+        loc = first_workspace_location(result)
+        return nil unless loc
+
+        path, line = normalize_location(loc)
+        Constant.new(name: result.name, path: path, line: line)
+      rescue StandardError
+        nil
+      end
+
+      # Returns Array[String] of ancestor class/module names.
+      # Uses Rubydex's +ancestors+ method which considers ALL class/module
+      # declarations (including external/framework ancestors) while the target
+      # declaration itself remains workspace-owned (via find_declaration).
+      def ancestors_of(name)
+        return [] unless @graph
+
+        decl = find_declaration(name)
+        return [] unless decl
+        return [] unless decl.respond_to?(:ancestors)
+
+        ancestors = decl.ancestors
+        return [] unless ancestors
+
+        ancestors.select { |ancestor| class_or_module?(ancestor) && ancestor.name != name }
+                 .map(&:name)
+      rescue StandardError
+        []
+      end
+
+      # Returns Array[String] of descendant class/module names.
+      # Gracefully returns [] if Rubydex cannot compute descendants.
+      def descendants_of(name)
+        return [] unless @graph
+
+        decl = find_declaration(name)
+        return [] unless decl
+        return [] unless decl.respond_to?(:descendants)
+
+        descendants = decl.descendants
+        return [] unless descendants
+
+        descendants.map(&:name).uniq - [name]
+      rescue StandardError
+        []
+      end
+
+      # Returns Array[Reference] for references to a given constant.
+      # Filters to workspace and rescues non-file URIs per reference.
+      def references_to(name)
+        return [] unless @graph
+
+        @graph.constant_references.filter_map do |ref|
+          next unless ref.respond_to?(:declaration) && ref.declaration&.name == name
+
+          loc = ref.location
+          next unless workspace_location?(loc)
+
+          path, line, column = normalize_location_full(loc)
+          Reference.new(name: name, path: path, line: line, column: column, context: nil)
+        rescue StandardError
+          nil
+        end
+      rescue StandardError
+        []
+      end
+
+      private
+
+      # ---- Pathname-based workspace containment ----
+
+      # Check if a file path is within the workspace using Pathname ancestry.
+      # This avoids string-prefix false positives like /workspace matching /workspace-other.
+      def workspace_path?(file_path)
+        return false unless file_path && !file_path.empty?
+
+        path_obj = Pathname.new(file_path)
+        path_obj == @root || path_obj.ascend.any? { |ancestor| ancestor == @root }
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      # Check if a Rubydex location points to a file within the workspace.
+      # Rescues non-file URIs (e.g. gem:// URIs) per location.
+      def workspace_location?(loc)
+        return false unless loc
+
+        file_path = location_file_path(loc)
+        return false unless file_path
+
+        workspace_path?(file_path)
+      rescue StandardError
+        false
+      end
+
+      def workspace_declaration?(decl)
+        return false unless decl.respond_to?(:definitions)
+
+        decl.definitions.any? do |defn|
+          workspace_location?(defn.location)
+        rescue StandardError
+          false
+        end
+      rescue StandardError
+        false
+      end
+
+      # ---- Definition site enumeration ----
+
+      # Returns all workspace-owned locations from a declaration's definitions.
+      # This ensures reopened classes expose all definition sites.
+      def workspace_definition_locations(decl)
+        return [] unless decl.respond_to?(:definitions)
+
+        decl.definitions.filter_map do |d|
+          d.location if workspace_location?(d.location)
+        rescue StandardError
+          nil
+        end
+      rescue StandardError
+        []
+      end
+
+      # Returns the first workspace-owned location from a declaration's definitions.
+      # Used for constant resolution where only the primary site is needed.
+      def first_workspace_location(decl)
+        return nil unless decl.respond_to?(:definitions)
+
+        defn = decl.definitions.find do |d|
+          workspace_location?(d.location)
+        rescue StandardError
+          false
+        end
+        defn&.location
+      rescue StandardError
+        nil
+      end
+
+      # ---- Location normalization (FiberAudit: 1-based lines, 0-based columns) ----
+
+      # Extracts the file system path from a rubydex location.
+      # Uses to_file_path which raises NotFileUriError for non-file URIs.
+      def location_file_path(loc)
+        loc.to_file_path
+      rescue ::Rubydex::Location::NotFileUriError, StandardError
+        nil
+      end
+
+      # Normalize a rubydex location to [path, line] for Declaration/Constant.
+      # Rubydex 0.2.9 reports start_line as zero-based; we add 1 for the
+      # FiberAudit one-based line convention.
+      def normalize_location(loc)
+        path = location_file_path(loc)
+        [path, loc.start_line + 1]
+      rescue StandardError
+        [nil, nil]
+      end
+
+      # Normalize a rubydex location to [path, line, column] for Reference.
+      # Rubydex 0.2.9 reports start_line as zero-based; we add 1 for the
+      # FiberAudit one-based line convention. Columns remain zero-based.
+      def normalize_location_full(loc)
+        path = location_file_path(loc)
+        [path, loc.start_line + 1, loc.start_column]
+      rescue StandardError
+        [nil, nil, nil]
+      end
+
+      def declaration_kind(decl)
+        case decl
+        when defined?(::Rubydex::Class) && ::Rubydex::Class
+          :class
+        when defined?(::Rubydex::Module) && ::Rubydex::Module
+          :module
+        when defined?(::Rubydex::Method) && ::Rubydex::Method
+          :method
+        else
+          :unknown
+        end
+      end
+
+      def class_or_module?(decl)
+        return false unless decl
+
+        (defined?(::Rubydex::Class) && decl.is_a?(::Rubydex::Class)) ||
+          (defined?(::Rubydex::Module) && decl.is_a?(::Rubydex::Module))
+      end
+
+      def find_declaration(name)
+        @graph.declarations.find do |d|
+          workspace_declaration?(d) && d.name == name.to_s
+        end
+      rescue StandardError
+        nil
+      end
+
+      # ---- Gap management ----
+
+      # Clears and deduplicates gaps on each build.
+      # Uses RubydexGap Data objects (not hashes).
+      def record_gaps
+        known_gaps = [
+          RubydexGap.new(
+            method: 'method_name_from_reference',
+            reason: 'Rubydex::MethodReference only exposes receiver and location, not the method name being called'
+          ),
+          RubydexGap.new(
+            method: 'ancestors_external',
+            reason: 'Rubydex ancestors may not include all external ancestors without explicit dependency indexing'
+          ),
+          RubydexGap.new(
+            method: 'call_site_extraction',
+            reason: 'Rubydex tracks method references without names or call context; Prism AST parsing needed'
+          ),
+          RubydexGap.new(
+            method: 'dynamic_methods',
+            reason: 'Rubydex may not fully track methods defined via define_method, method_missing, or other metaprogramming'
+          ),
+          RubydexGap.new(
+            method: 'def_delegator_tracking',
+            reason: 'Forwardable def_delegator creates method aliases that Rubydex may not fully resolve to their target'
+          )
+        ]
+
+        @gaps = (known_gaps + @gaps).uniq
+      end
+    end
+  end
+end

data/lib/fiber_audit/suppressions/parser.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'prism'
+require_relative '../errors'
+
+module FiberAudit
+  module Suppressions
+    InlineSuppression = Data.define(
+      :rule_id, :reason, :path, :start_line, :end_line
+    )
+    YamlSuppression = Data.define(:rule, :symbol, :operation, :reason)
+
+    class Parser
+      class << self
+        # Parses inline suppressions from a file's content using Prism
+        # for comment detection.
+        # Directives are recognized ONLY from actual Prism comments -
+        # never from raw text scans. This ensures directive text in
+        # strings, heredocs, and regex literals cannot start or end
+        # suppressions.
+        def parse_inline(path, content)
+          result = Prism.parse(content)
+          return [] if result.errors.any?
+
+          lines = content.lines
+          disables = []
+          enables = []
+
+          # Only examine actual comments from Prism
+          result.comments.each do |comment|
+            text = comment.location.slice
+            line_num = comment.location.start_line
+
+            if (match = text.match(
+              /fiber-audit:disable\s+(FA\d+)/
+            ))
+              rule_id = match[1]
+              reason = extract_reason(text, path, line_num)
+              is_block = block_comment?(comment, lines)
+              disables << {
+                rule_id: rule_id,
+                reason: reason,
+                line: line_num,
+                block: is_block
+              }
+            elsif (match = text.match(
+              /fiber-audit:enable\s+(FA\d+)/
+            ))
+              enables << {
+                rule_id: match[1],
+                line: line_num
+              }
+            end
+          end
+
+          build_suppressions(disables, enables, lines, path)
+        end
+
+        # Parse YAML suppressions file
+        def parse_yaml(path)
+          return [] unless path && File.exist?(path)
+
+          yaml = YAML.safe_load_file(path) || {}
+          raw_suppressions = yaml['suppressions'] || []
+
+          raw_suppressions.map do |entry|
+            rule = entry['rule']
+            reason = entry['reason']
+
+            if reason.nil? || reason.strip.empty?
+              raise FiberAudit::ConfigurationError,
+                    "YAML suppression for rule #{rule} at #{path} " \
+                    "missing 'reason'"
+            end
+
+            YamlSuppression.new(
+              rule: rule,
+              symbol: entry['symbol'],
+              operation: entry['operation'],
+              reason: reason.strip
+            )
+          end
+        end
+
+        private
+
+        # Extract and validate reason from comment text
+        def extract_reason(text, path, line_number)
+          match = text.match(/--\s+(.+)$/)
+          if match.nil? || match[1].strip.empty?
+            raise FiberAudit::ConfigurationError,
+                  "Inline suppression at #{path}:#{line_number} " \
+                  'missing reason (use -- <reason>)'
+          end
+          match[1].strip
+        end
+
+        # Determine if comment is a block comment (only whitespace
+        # before #) vs a trailing comment (has code before #)
+        def block_comment?(comment, lines)
+          line = lines[comment.location.start_line - 1]
+          prefix = line[0, comment.location.start_column]
+          prefix.nil? || prefix.strip.empty?
+        end
+
+        # Build InlineSuppression objects, matching enables to disables
+        def build_suppressions(disables, enables, lines, path)
+          used_enable_lines = []
+
+          disables.map do |d|
+            end_line = if d[:block]
+                         enable = find_matching_enable(
+                           d, enables, used_enable_lines
+                         )
+                         if enable
+                           used_enable_lines << enable[:line]
+                           enable[:line]
+                         else
+                           lines.size
+                         end
+                       else
+                         d[:line]
+                       end
+
+            InlineSuppression.new(
+              rule_id: d[:rule_id],
+              reason: d[:reason],
+              path: path,
+              start_line: d[:line],
+              end_line: end_line
+            )
+          end
+        end
+
+        def find_matching_enable(disable, enables, used_lines)
+          enables.find do |e|
+            e[:rule_id] == disable[:rule_id] &&
+              e[:line] > disable[:line] &&
+              !used_lines.include?(e[:line])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/suppressions/store.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative 'parser'
+
+module FiberAudit
+  module Suppressions
+    class Store
+      attr_reader :inline_suppressions, :yaml_suppressions
+
+      def initialize(inline_suppressions: [], yaml_suppressions: [])
+        @inline_suppressions = inline_suppressions
+        @yaml_suppressions = yaml_suppressions
+      end
+
+      # Returns [active_findings, suppressed_findings]
+      def apply(findings)
+        suppressed = []
+        active = []
+
+        findings.each do |finding|
+          if suppressed?(finding)
+            suppressed << finding
+          else
+            active << finding
+          end
+        end
+
+        [active, suppressed]
+      end
+
+      private
+
+      def suppressed?(finding)
+        return true if yaml_suppressed?(finding)
+        return true if inline_suppressed?(finding)
+
+        false
+      end
+
+      def yaml_suppressed?(finding)
+        @yaml_suppressions.any? do |sup|
+          next false unless sup.rule == finding.rule_id
+          next false if sup.symbol && sup.symbol != finding.symbol
+          next false if sup.operation && sup.operation != finding.operation
+
+          true
+        end
+      end
+
+      def inline_suppressed?(finding)
+        return false unless finding.location
+
+        path = finding.location.path
+        line = finding.location.line
+
+        @inline_suppressions.any? do |sup|
+          sup.path == path && line >= sup.start_line && line <= sup.end_line &&
+            sup.rule_id == finding.rule_id
+        end
+      end
+    end
+  end
+end

data/lib/fiber_audit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FiberAudit
+  VERSION = '0.1.0'
+end

data/lib/fiber_audit.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'fiber_audit/version'
+require_relative 'fiber_audit/errors'
+require_relative 'fiber_audit/findings/severity'
+require_relative 'fiber_audit/findings/confidence'
+require_relative 'fiber_audit/findings/location'
+require_relative 'fiber_audit/findings/evidence'
+require_relative 'fiber_audit/correlation/fingerprint'
+require_relative 'fiber_audit/findings/finding'
+require_relative 'fiber_audit/findings/collection'
+require_relative 'fiber_audit/configuration'
+require_relative 'fiber_audit/suppressions/parser'
+require_relative 'fiber_audit/suppressions/store'
+require_relative 'fiber_audit/execution_context'
+require_relative 'fiber_audit/static/semantic_index'
+require_relative 'fiber_audit/static/call_site'
+require_relative 'fiber_audit/static/call_site_extractor'
+require_relative 'fiber_audit/static/execution_context_resolver'
+require_relative 'fiber_audit/static/rules/base'
+require_relative 'fiber_audit/static/rules/registry'
+require_relative 'fiber_audit/static/rules/blocking_subprocess'
+require_relative 'fiber_audit/static/rules/thread_join'
+require_relative 'fiber_audit/static/rules/synchronization'
+require_relative 'fiber_audit/static/rules/thread_current_state'
+require_relative 'fiber_audit/static/rules/io_select'
+require_relative 'fiber_audit/static/rules/direct_socket'
+require_relative 'fiber_audit/static/rules/net_http_in_request'
+require_relative 'fiber_audit/static/rules/built_ins'
+require_relative 'fiber_audit/reporters/base'
+require_relative 'fiber_audit/reporters/schema'
+require_relative 'fiber_audit/reporters/text'
+require_relative 'fiber_audit/reporters/json'
+require_relative 'fiber_audit/project'
+require_relative 'fiber_audit/audit'
+require_relative 'fiber_audit/cli'
+
+module FiberAudit
+  # Public entry point — expanded as work packages are implemented
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: fiber_audit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- FiberAudit Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: prism
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubydex
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+executables:
+- fiber-audit
+extensions: []
+extra_rdoc_files: []
+files:
+- ".fiber-audit.example.yml"
+- CHANGELOG.md
+- README.md
+- bin/fiber-audit
+- lib/fiber_audit.rb
+- lib/fiber_audit/audit.rb
+- lib/fiber_audit/cli.rb
+- lib/fiber_audit/configuration.rb
+- lib/fiber_audit/correlation/fingerprint.rb
+- lib/fiber_audit/errors.rb
+- lib/fiber_audit/execution_context.rb
+- lib/fiber_audit/findings/collection.rb
+- lib/fiber_audit/findings/confidence.rb
+- lib/fiber_audit/findings/evidence.rb
+- lib/fiber_audit/findings/finding.rb
+- lib/fiber_audit/findings/location.rb
+- lib/fiber_audit/findings/severity.rb
+- lib/fiber_audit/project.rb
+- lib/fiber_audit/reporters/base.rb
+- lib/fiber_audit/reporters/json.rb
+- lib/fiber_audit/reporters/schema.rb
+- lib/fiber_audit/reporters/text.rb
+- lib/fiber_audit/static/call_site.rb
+- lib/fiber_audit/static/call_site_extractor.rb
+- lib/fiber_audit/static/execution_context_resolver.rb
+- lib/fiber_audit/static/rules/base.rb
+- lib/fiber_audit/static/rules/blocking_subprocess.rb
+- lib/fiber_audit/static/rules/built_ins.rb
+- lib/fiber_audit/static/rules/direct_socket.rb
+- lib/fiber_audit/static/rules/io_select.rb
+- lib/fiber_audit/static/rules/net_http_in_request.rb
+- lib/fiber_audit/static/rules/registry.rb
+- lib/fiber_audit/static/rules/synchronization.rb
+- lib/fiber_audit/static/rules/thread_current_state.rb
+- lib/fiber_audit/static/rules/thread_join.rb
+- lib/fiber_audit/static/semantic_index.rb
+- lib/fiber_audit/suppressions/parser.rb
+- lib/fiber_audit/suppressions/store.rb
+- lib/fiber_audit/version.rb
+homepage: https://github.com/vdombr/fiber_audit
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/vdombr/fiber_audit
+  changelog_uri: https://github.com/vdombr/fiber_audit/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Static fiber-scheduler compatibility auditor for Ruby and Rails applications
+test_files: []