sixth_sense 0.1.0

data/lib/sixth_sense/adapters/test_unit.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "prism"
+
+require_relative "../framework_adapter"
+require_relative "../model"
+require_relative "../source_location"
+require_relative "rspec"
+
+module SixthSense
+  module Adapters
+    class TestUnit < FrameworkAdapter
+      ASSERTION_PREFIXES = %w[assert assert_ flunk].freeze
+
+      def handles?(path)
+        return false unless path.end_with?("_test.rb")
+        return false unless File.file?(path)
+
+        File.read(path).match?(/\bTest::Unit::TestCase\b/)
+      end
+
+      def parse(path)
+        parsed = Prism.parse_file(path)
+        unless parsed.success?
+          messages = parsed.errors.map(&:message).join(", ")
+          raise Error, "failed to parse #{path}: #{messages}"
+        end
+
+        Model::TestFile.new(
+          path: path,
+          framework: :test_unit,
+          test_cases: Parser.new(path, parsed.value).test_cases,
+          sut_candidates: map_to_sut_path(path),
+          metadata: {}
+        )
+      end
+
+      def run_with_coverage(test_files:, isolation:)
+        require_relative "../runners/coverage_runner"
+
+        Runners::CoverageRunner.new.run(test_files: test_files, isolation: isolation)
+      end
+
+      def mutation_session(test_files:)
+        { framework: :test_unit, test_files: test_files.map(&:path), runner: "ruby" }
+      end
+
+      def map_to_sut(test_file)
+        map_to_sut_path(test_file.path)
+      end
+
+      private
+
+      def map_to_sut_path(test_path)
+        relative = test_path.tr("\\", "/").sub(%r{\A(?:.*?/)?(?:test|test_unit)/}, "").sub(/_test\.rb\z/, ".rb")
+        root = project_root_for(test_path)
+        candidates = [File.join("lib", relative), File.join("app", relative), relative]
+        if root
+          candidates << File.join(root, "lib", relative)
+          candidates << File.join(root, "app", relative)
+        end
+        candidates.uniq.filter_map do |candidate|
+          next unless File.file?(candidate)
+
+          Adapters::RSpec::CodeUnitExtractor.new(candidate).code_unit
+        end
+      end
+
+      def project_root_for(test_path)
+        normalized = test_path.tr("\\", "/")
+        match = %r{\A(.+?)/(?:test|test_unit)/}.match(normalized)
+        match&.[](1)
+      end
+
+      class Parser
+        def initialize(path, ast)
+          @path = path
+          @ast = ast
+        end
+
+        def test_cases
+          cases = []
+          walk(@ast) do |node|
+            next unless node.is_a?(Prism::DefNode)
+            next unless node.name.to_s.start_with?("test_")
+
+            cases << test_case_for(node)
+          end
+          cases
+        end
+
+        private
+
+        def test_case_for(node)
+          body = node.slice.to_s
+          Model::TestCase.new(
+            id: "#{@path}:#{node.name}",
+            description: node.name.to_s.tr("_", " "),
+            location: location_for(node),
+            assertions: assertions_for(node),
+            ast: node,
+            body: body,
+            metadata: {}
+          )
+        end
+
+        def assertions_for(node)
+          assertions = []
+          walk(node) do |child|
+            next unless child.is_a?(Prism::CallNode)
+            next unless assertion_call?(child.name)
+
+            assertions << Model::Assertion.new(
+              location: location_for(child),
+              matcher: child.name,
+              subject_expr: child.arguments&.arguments&.map(&:slice)&.join(", "),
+              message: nil
+            )
+          end
+          assertions
+        end
+
+        def assertion_call?(name)
+          ASSERTION_PREFIXES.any? { |prefix| name.to_s.start_with?(prefix) }
+        end
+
+        def walk(node, &block)
+          return unless node
+
+          yield node
+          node.each_child_node { |child| walk(child, &block) }
+        end
+
+        def location_for(node)
+          SourceLocation.new(path: @path, line: node.location.start_line, column: node.location.start_column + 1)
+        end
+      end
+    end
+  end
+end
+
+SixthSense::FrameworkAdapter.register(:test_unit, SixthSense::Adapters::TestUnit)

data/lib/sixth_sense/analysis_context.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SixthSense
+  class AnalysisContext
+    attr_reader :config, :coverage_maps, :checked_coverage_maps, :kill_matrices, :warnings
+
+    def initialize(config: {}, coverage_maps: {}, checked_coverage_maps: {}, kill_matrices: {}, warnings: [])
+      @config = config
+      @coverage_maps = coverage_maps
+      @checked_coverage_maps = checked_coverage_maps
+      @kill_matrices = kill_matrices
+      @warnings = warnings
+    end
+
+    def coverage_map_for(test_file)
+      coverage_maps[test_file.path]
+    end
+
+    def checked_coverage_map_for(test_file)
+      checked_coverage_maps[test_file.path]
+    end
+
+    def kill_matrix_for(test_file)
+      kill_matrices[test_file.path]
+    end
+
+    def config_fetch(*keys, default: nil)
+      keys.reduce(config) do |current, key|
+        break default unless current.respond_to?(:fetch)
+
+        current.fetch(key.to_s) { current.fetch(key.to_sym, default) }
+      end
+    end
+  end
+end

data/lib/sixth_sense/analysis_runner.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "analysis_context"
+require_relative "config"
+require_relative "framework_adapter"
+require_relative "model"
+require_relative "mutation_cache"
+require_relative "runners/checked_coverage_estimator"
+require_relative "runners/checked_coverage_runner"
+require_relative "runners/coverage_runner"
+require_relative "scoring/aggregator"
+
+module SixthSense
+  class AnalysisRunner
+    attr_reader :config
+
+    def initialize(config: Config.load)
+      @config = config
+    end
+
+    def analyze(paths:, level:)
+      warnings = []
+      test_files = discover(paths).filter_map do |path|
+        adapter_class = FrameworkAdapter.for_path(path)
+        unless adapter_class
+          warnings << "No framework adapter accepted #{path}."
+          next
+        end
+
+        apply_configured_mapping(adapter_class.new.parse(path))
+      rescue Error => error
+        warnings << "#{path}: #{error.class}: #{error.message}"
+        nil
+      end
+
+      coverage_maps = collect_coverage(test_files, level, warnings)
+      checked_maps = collect_checked_coverage(test_files, coverage_maps, level, warnings)
+      kill_matrices = collect_mutation(test_files, level, warnings)
+      context = AnalysisContext.new(
+        config: config.data,
+        coverage_maps: coverage_maps,
+        checked_coverage_maps: checked_maps,
+        kill_matrices: kill_matrices,
+        warnings: warnings
+      )
+      aggregator = Scoring::Aggregator.new(level: level)
+      test_files.map { |test_file| aggregator.analyze(test_file, context) }
+    end
+
+    def discover(paths)
+      selected = paths.empty? ? ["spec"] : paths
+      selected.flat_map { |path| expand_path(path) }.uniq.sort
+    end
+
+    private
+
+    def apply_configured_mapping(test_file)
+      mapping = config.fetch(:mapping, test_file.path, default: nil)
+      return test_file unless mapping
+
+      explicit_paths = Array(mapping["paths"] || mapping[:paths])
+      explicit_units = explicit_paths.filter_map do |path|
+        next unless File.file?(path)
+
+        Adapters::RSpec::CodeUnitExtractor.new(path).code_unit
+      end
+      test_file.sut_candidates = explicit_units unless explicit_units.empty?
+      test_file.metadata ||= {}
+      test_file.metadata[:mutation_subjects] = Array(mapping["subjects"] || mapping[:subjects])
+      test_file
+    end
+
+    def collect_coverage(test_files, level, warnings)
+      return {} if level < 1 || test_files.empty?
+      return {} unless config.fetch(:coverage, :enabled, default: true)
+
+      Runners::CoverageRunner.new(config: config.fetch(:coverage, default: {})).run(test_files: test_files)
+    rescue Error, NotImplementedError => error
+      warnings << "coverage disabled: #{error.message}"
+      {}
+    end
+
+    def collect_checked_coverage(test_files, coverage_maps, level, warnings)
+      return {} if level < 1 || test_files.empty?
+
+      traced = Runners::CheckedCoverageRunner.new(config: config.fetch(:coverage, default: {})).run(test_files: test_files)
+      estimator = Runners::CheckedCoverageEstimator.new
+      test_files.each_with_object({}) do |test_file, maps|
+        coverage_map = coverage_maps[test_file.path]
+        trace_map = traced[test_file.path]
+        estimated = coverage_map ? estimator.estimate(test_file, coverage_map) : nil
+        maps[test_file.path] = merge_checked_coverage(trace_map, estimated)
+      end.reject { |_path, map| map.checked_ratio.nil? }
+    rescue Error, NotImplementedError => error
+      warnings << "checked coverage trace disabled: #{error.message}"
+      estimator = Runners::CheckedCoverageEstimator.new
+      test_files.each_with_object({}) do |test_file, maps|
+        coverage_map = coverage_maps[test_file.path]
+        maps[test_file.path] = estimator.estimate(test_file, coverage_map) if coverage_map
+      end
+    end
+
+    def merge_checked_coverage(trace_map, estimated)
+      return estimated unless trace_map
+      return trace_map unless estimated
+
+      checked = trace_map.per_test_checked_lines.merge(estimated.per_test_checked_lines) do |_test_id, traced_lines, estimated_lines|
+        merge_line_hashes(traced_lines, estimated_lines)
+      end
+      executed = merge_line_hashes(trace_map.executed_lines, estimated.executed_lines)
+      Model::CheckedCoverageMap.new(per_test_checked_lines: checked, executed_lines: executed)
+    end
+
+    def merge_line_hashes(left, right)
+      (left.keys + right.keys).uniq.to_h do |path|
+        [path, (Array(left[path]) + Array(right[path])).uniq]
+      end
+    end
+
+    def collect_mutation(test_files, level, warnings)
+      return {} if level < 2 || test_files.empty?
+
+      cache = MutationCache.new(root: config.fetch(:mutation, :cache_dir, default: MutationCache::DEFAULT_ROOT))
+      test_files.each_with_object({}) do |test_file, matrices|
+        matrix = cache.load(test_file)
+        if matrix
+          matrices[test_file.path] = matrix
+        else
+          warnings << "mutation cache missing for #{test_file.path}; run a matrix producer and write #{cache.path_for(test_file.path)}"
+        end
+      end
+    end
+
+    def expand_path(path)
+      return [path] if File.file?(path)
+      return Dir[File.join(path, "**", "*_spec.rb")] + Dir[File.join(path, "**", "*_test.rb")] if File.directory?(path)
+
+      Dir[path]
+    end
+  end
+end

data/lib/sixth_sense/analyzer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "result"
+
+module SixthSense
+  AnalyzerResult = Struct.new(:analyzer_id, :axis, :score, :confidence, :findings, :measured, keyword_init: true) do
+    def measured?
+      measured != false && !score.nil?
+    end
+  end
+
+  class Analyzer
+    class << self
+      def inherited(subclass)
+        super
+        SixthSense.register_analyzer(subclass)
+      end
+
+      def analyzer_id(id = nil)
+        return @analyzer_id unless id
+
+        @analyzer_id = id
+      end
+
+      def axis(value = nil)
+        return @axis unless value
+
+        @axis = value
+      end
+
+      def level(value = nil)
+        return @level unless value
+
+        @level = value
+      end
+
+      def reference(authors:, title:, venue:, year:, doi: nil)
+        references << Result::Reference.new(
+          authors: authors,
+          title: title,
+          venue: venue,
+          year: year,
+          doi: doi
+        )
+      end
+
+      def references
+        @references ||= []
+      end
+    end
+
+    def analyze(_test_file, _context)
+      raise NotImplementedError
+    end
+
+    private
+
+    def result(score:, findings:, confidence:, measured: true)
+      AnalyzerResult.new(
+        analyzer_id: self.class.analyzer_id,
+        axis: self.class.axis,
+        score: score,
+        confidence: confidence,
+        findings: findings,
+        measured: measured
+      )
+    end
+
+    def unmeasured(confidence: :low, findings: [])
+      result(score: nil, findings: findings, confidence: confidence, measured: false)
+    end
+
+    def finding(rule_id:, severity:, location:, message:, suggestion: nil)
+      Result::Finding.new(
+        analyzer_id: self.class.analyzer_id,
+        rule_id: rule_id,
+        severity: severity,
+        location: location,
+        message: message,
+        references: self.class.references,
+        suggestion: suggestion
+      )
+    end
+  end
+end

data/lib/sixth_sense/analyzers/adequacy_checked_coverage.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../analyzer"
+require_relative "../source_location"
+
+module SixthSense
+  module Analyzers
+    class AdequacyCheckedCoverage < Analyzer
+      analyzer_id "adequacy/checked_coverage"
+      axis :adequacy
+      level 1
+
+      reference authors: "Schuler, D.; Zeller, A.",
+                title: "Assessing Oracle Quality with Checked Coverage",
+                venue: "ICST",
+                year: 2011,
+                doi: "10.1109/ICST.2011.32"
+
+      # Paper basis: Schuler/Zeller 2011 (doi:10.1109/ICST.2011.32)
+      # defines checked coverage as executed code associated with an oracle.
+      def analyze(test_file, context)
+        checked = context.checked_coverage_map_for(test_file)
+        return unmeasured(confidence: :low) unless checked&.checked_ratio
+
+        findings = checked.unchecked_lines.first(10).map do |path, line|
+          finding(
+            rule_id: "unchecked_executed_line",
+            severity: :info,
+            location: SourceLocation.new(path: path, line: line, column: 1),
+            message: "Executed line was not associated with an assertion subject.",
+            suggestion: "Add an assertion that observes this behavior if it is semantically important."
+          )
+        end
+
+        result(score: (checked.checked_ratio * 100.0).round(2), findings: findings, confidence: :medium)
+      end
+    end
+  end
+end

data/lib/sixth_sense/analyzers/adequacy_coverage.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative "../analyzer"
+
+module SixthSense
+  module Analyzers
+    class AdequacyCoverage < Analyzer
+      analyzer_id "adequacy/coverage"
+      axis :adequacy
+      level 1
+
+      reference authors: "Zhu, H.; Hall, P. A. V.; May, J. H. R.",
+                title: "Software Unit Test Coverage and Adequacy",
+                venue: "ACM Computing Surveys",
+                year: 1997,
+                doi: "10.1145/267580.267590"
+      reference authors: "Inozemtseva, L.; Holmes, R.",
+                title: "Coverage Is Not Strongly Correlated with Test Suite Effectiveness",
+                venue: "ICSE",
+                year: 2014,
+                doi: "10.1145/2568225.2568271"
+
+      # Paper basis: Zhu/Hall/May 1997 (doi:10.1145/267580.267590)
+      # surveys coverage adequacy criteria; branch coverage is preferred when present.
+      def analyze(test_file, context)
+        coverage = context.coverage_map_for(test_file)
+        return unmeasured(confidence: :low) unless coverage
+
+        branch_ratio = coverage.branch_coverage_ratio
+        line_ratio = coverage.line_coverage_ratio
+        ratio = branch_ratio || line_ratio
+        return unmeasured(confidence: :low) unless ratio
+
+        score = (score_ratio(ratio, context) * 100.0).round(2)
+        confidence = branch_ratio ? :medium : :low
+        findings = []
+        if ratio < 0.8
+          findings << finding(
+            rule_id: "low_coverage",
+            severity: :warning,
+            location: test_file.test_cases.first&.location,
+            message: "Coverage ratio is #{(ratio * 100).round(1)}%.",
+            suggestion: "Add tests for unexecuted branches before relying on adequacy scores."
+          )
+        end
+
+        result(score: score, findings: findings, confidence: confidence)
+      end
+
+      private
+
+      # Paper basis: Inozemtseva/Holmes 2014 (doi:10.1145/2568225.2568271)
+      # motivates calibrated mode; raw mode keeps the paper-exact coverage ratio.
+      def score_ratio(ratio, context)
+        transform = context.config_fetch(:adequacy, :coverage_transform, default: "raw").to_s
+        return ratio unless transform == "calibrated"
+
+        gamma = context.config_fetch(:adequacy, :coverage_gamma, default: 0.5).to_f
+        1.0 - ((1.0 - ratio)**gamma)
+      end
+    end
+  end
+end

data/lib/sixth_sense/analyzers/adequacy_mutation.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "../analyzer"
+
+module SixthSense
+  module Analyzers
+    class AdequacyMutation < Analyzer
+      analyzer_id "adequacy/mutation"
+      axis :adequacy
+      level 2
+
+      reference authors: "Jia, Y.; Harman, M.",
+                title: "An Analysis and Survey of the Development of Mutation Testing",
+                venue: "IEEE Transactions on Software Engineering",
+                year: 2011,
+                doi: "10.1109/TSE.2010.62"
+      reference authors: "Just, R. et al.",
+                title: "Are Mutants a Valid Substitute for Real Faults in Software Testing?",
+                venue: "FSE",
+                year: 2014,
+                doi: "10.1145/2635868.2635929"
+
+      # Paper basis: Jia/Harman 2011 (doi:10.1109/TSE.2010.62) defines
+      # mutation score; Just et al. 2014 (doi:10.1145/2635868.2635929)
+      # supports mutants as a proxy for real fault detection.
+      def analyze(test_file, context)
+        matrix = context.kill_matrix_for(test_file)
+        return no_subjects(test_file) if !matrix && test_file.sut_candidates.empty?
+        if matrix && !matrix.mutation_score
+          return result(score: nil, measured: false, confidence: :low, findings: operational_findings(matrix, context))
+        end
+        return unmeasured(confidence: :low) unless matrix&.mutation_score
+
+        findings = operational_findings(matrix, context)
+        findings.concat(matrix.surviving_mutants.map do |mutant|
+          finding(
+            rule_id: mutant.status.to_s == "timeout" ? "mutation_timeout" : "surviving_mutant",
+            severity: :warning,
+            location: mutant.location,
+            message: mutant_message(mutant),
+            suggestion: mutant_suggestion(mutant)
+          )
+        end)
+
+        result(score: (matrix.mutation_score * 100.0).round(2), findings: findings, confidence: confidence_for(matrix))
+      end
+
+      private
+
+      def no_subjects(test_file)
+        result(
+          score: nil,
+          measured: false,
+          confidence: :low,
+          findings: [
+            finding(
+              rule_id: "no_subjects",
+              severity: :warning,
+              location: test_file.test_cases.first&.location,
+              message: "No mutation subjects were inferred for this test file.",
+              suggestion: "Add an explicit mapping entry with mutation subjects or SUT paths."
+            )
+          ]
+        )
+      end
+
+      # Paper basis: Jia/Harman 2011 discusses equivalent mutants and
+      # operational mutation-analysis threats such as timeouts/sampling.
+      def operational_findings(matrix, context)
+        findings = warning_findings(matrix)
+        if matrix.sampled?
+          findings << finding(
+            rule_id: "sampled_mutants",
+            severity: :info,
+            location: nil,
+            message: "Mutation analysis used a deterministic sample because generated mutants exceeded the configured limit.",
+            suggestion: "Increase mutation.max_mutants or run a narrower target for full precision."
+          )
+        end
+        if matrix.timeout_ratio > 0.2
+          findings << finding(
+            rule_id: "timeout_rate_high",
+            severity: :warning,
+            location: nil,
+            message: "More than 20% of counted mutants timed out.",
+            suggestion: "Increase mutation.timeout or inspect timeout-prone code before trusting the score."
+          )
+        end
+        threshold = context.config_fetch(:mutation, :equivalent_threshold, default: 0.2).to_f
+        if matrix.equivalent_ratio > threshold
+          findings << finding(
+            rule_id: "equivalent_rate_high",
+            severity: :warning,
+            location: nil,
+            message: "Equivalent mutant annotations exceed the configured threshold.",
+            suggestion: "Review equivalent annotations to avoid hiding real surviving mutants."
+          )
+        end
+        findings
+      end
+
+      def warning_findings(matrix)
+        Array((matrix.metadata || {})["warnings"]).map do |warning|
+          type = warning.is_a?(Hash) ? warning.fetch("type", "mutation_warning") : "mutation_warning"
+          message = warning.is_a?(Hash) ? warning.fetch("message", warning.inspect) : warning.to_s
+          finding(
+            rule_id: type,
+            severity: :warning,
+            location: nil,
+            message: message,
+            suggestion: suggestion_for_warning(type)
+          )
+        end
+      end
+
+      def suggestion_for_warning(type)
+        return "Fix or quarantine the failing baseline test before trusting mutation results." if type.to_s == "unstable_baseline"
+
+        "Review mutation execution settings."
+      end
+
+      def confidence_for(matrix)
+        return :medium if matrix.sampled? || matrix.timeout_ratio > 0.2
+
+        :high
+      end
+
+      def mutant_message(mutant)
+        return "Mutant #{mutant.id} timed out." if mutant.status.to_s == "timeout"
+
+        "Mutant #{mutant.id} survived."
+      end
+
+      def mutant_suggestion(mutant)
+        return "Increase timeout or add a faster assertion that distinguishes this mutation." if mutant.status.to_s == "timeout"
+
+        mutant.killing_hint || "Add an expectation that distinguishes this mutation."
+      end
+    end
+  end
+end

data/lib/sixth_sense/analyzers/quality_assertion_density.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "../analyzer"
+
+module SixthSense
+  module Analyzers
+    class QualityAssertionDensity < Analyzer
+      analyzer_id "quality/assertion_density"
+      axis :quality
+      level 0
+
+      reference authors: "Kudrjavets, G.; Nagappan, N.; Ball, T.",
+                title: "Assessing the Relationship between Software Assertions and Faults",
+                venue: "ISSRE",
+                year: 2006,
+                doi: "10.1109/ISSRE.2006.14"
+
+      # Paper basis: Kudrjavets/Nagappan/Ball 2006
+      # (doi:10.1109/ISSRE.2006.14) links assertion density with fault outcomes.
+      def analyze(test_file, context)
+        executable_loc = [test_file.executable_loc, 1].max
+        density = test_file.assertions.length.to_f / executable_loc
+        density_min = context.config_fetch(:quality, :assertion_density_min, default: 0.05)
+        return result(score: 100.0, findings: [], confidence: :high) if density >= density_min
+
+        penalty = (1.0 - (density / density_min)) * 10.0
+        findings = [
+          finding(
+            rule_id: "low_assertion_density",
+            severity: :warning,
+            location: test_file.test_cases.first&.location,
+            message: "Assertion density is #{density.round(3)} per executable test line.",
+            suggestion: "Add explicit expectations for the behavior this file exercises."
+          )
+        ]
+
+        result(score: (100.0 - penalty).round(2), findings: findings, confidence: :high)
+      end
+    end
+  end
+end