tina4ruby 3.13.37 → 3.13.39

data/lib/tina4/metrics.rb

@@ -353,6 +353,124 @@ module Tina4
       result
     end
 
+    # ── Top Offenders (CLI + dashboard) ──────────────────────────
+
+    # Severity ranking for sorting (higher = more severe).
+    SEVERITY_RANK = { "error" => 2, "warn" => 1, "info" => 0 }.freeze
+
+    # Rank the worst code-quality issues into a single "top offenders" list.
+    #
+    # Reuses full_analysis (does NOT re-analyze). Each offender is a hash:
+    #   {"file", "line", "kind", "severity", "score", "detail"}
+    #
+    # Rules (one offender per matching condition):
+    #   - function complexity > 10  → kind "complexity"
+    #         severity "error" if >20 else "warn"; score = complexity
+    #   - file loc > 500            → kind "large_file" (warn); score = loc/100
+    #   - file functions > 20       → kind "too_many_functions" (warn); score = functions/4
+    #   - file maintainability < 40 → kind "low_maintainability"
+    #         severity "error" if <20 else "warn"; score = (50 - mi)
+    #   - file has_tests false      → kind "untested" (info); score = loc/100
+    #
+    # Sorted by (severity rank, score) DESCENDING and truncated to `top`.
+    #
+    # Returns {"offenders" => [...], "summary" => {...}} where summary carries
+    # the headline numbers the CLI prints (files_analyzed, total_functions,
+    # avg_complexity, avg_maintainability, scan_mode, scan_root, and the total
+    # offender count before truncation).
+    def self.offenders(root = 'src', top = 20)
+      analysis = full_analysis(root)
+      if analysis.key?("error")
+        return { "offenders" => [], "summary" => { "error" => analysis["error"] } }
+      end
+
+      items = []
+
+      # Function-level: cyclomatic complexity.
+      (analysis["most_complex_functions"] || []).each do |fn|
+        cc = fn["complexity"]
+        next unless cc > 10
+        items << {
+          "file" => fn["file"],
+          "line" => fn["line"],
+          "kind" => "complexity",
+          "severity" => cc > 20 ? "error" : "warn",
+          "score" => cc.to_f,
+          "detail" => "#{fn['name']} — cyclomatic complexity #{cc}"
+        }
+      end
+
+      # File-level rules.
+      (analysis["file_metrics"] || []).each do |fm|
+        path = fm["path"]
+        loc = fm["loc"]
+        funcs = fm["functions"]
+        mi = fm["maintainability"]
+
+        if loc > 500
+          items << {
+            "file" => path,
+            "line" => 1,
+            "kind" => "large_file",
+            "severity" => "warn",
+            "score" => loc / 100.0,
+            "detail" => "#{loc} LOC (max 500)"
+          }
+        end
+
+        if funcs > 20
+          items << {
+            "file" => path,
+            "line" => 1,
+            "kind" => "too_many_functions",
+            "severity" => "warn",
+            "score" => funcs / 4.0,
+            "detail" => "#{funcs} functions (max 20)"
+          }
+        end
+
+        if mi < 40
+          items << {
+            "file" => path,
+            "line" => 1,
+            "kind" => "low_maintainability",
+            "severity" => mi < 20 ? "error" : "warn",
+            "score" => 50 - mi,
+            "detail" => "maintainability index #{mi} (min 40)"
+          }
+        end
+
+        if fm["has_tests"] == false
+          items << {
+            "file" => path,
+            "line" => 1,
+            "kind" => "untested",
+            "severity" => "info",
+            "score" => loc / 100.0,
+            "detail" => "no referencing test"
+          }
+        end
+      end
+
+      # Sort by (severity rank, score) DESCENDING — stable so insertion order
+      # breaks ties deterministically.
+      items = items.each_with_index.sort_by do |o, idx|
+        [-SEVERITY_RANK[o["severity"]], -o["score"], idx]
+      end.map(&:first)
+
+      summary = {
+        "files_analyzed" => analysis["files_analyzed"],
+        "total_functions" => analysis["total_functions"],
+        "avg_complexity" => analysis["avg_complexity"],
+        "avg_maintainability" => analysis["avg_maintainability"],
+        "scan_mode" => analysis["scan_mode"],
+        "scan_root" => analysis["scan_root"],
+        "total_offenders" => items.length
+      }
+
+      { "offenders" => items.first(top), "summary" => summary }
+    end
+
     # ── File Detail ─────────────────────────────────────────────
 
     def self.file_detail(file_path)
@@ -423,64 +541,140 @@ module Tina4
 
     private_class_method
 
+    # Check whether a source file has a test that actually exercises it.
+    #
+    # PRECISE detection (a bare word-mention is NOT enough — that over-reported
+    # badly: `sqlite3_adapter.rb` looked "tested" because some spec merely said
+    # "sqlite3_adapter"):
+    #
+    #   1. Filename — a dedicated `<module>_spec.rb` / `<module>_test.rb` /
+    #      `test_<module>.rb` for THIS exact module (NOT the parent directory —
+    #      one `database_spec.rb` must not mark every file under `database/`
+    #      tested).
+    #   2. Require — a spec that actually requires this file: its require path
+    #      (`require "tina4/database/sqlite"` / `require_relative ".../sqlite"`)
+    #      matched by the basename of a require target. A constant/class that is
+    #      genuinely DEFINED in this file (top-level class/module) referenced by
+    #      a spec also counts.
+    #
+    # Returns true only on a real, file-specific signal — so the "untested"
+    # offenders surfaced by `tina4 metrics` and the dashboard "T" badge are
+    # trustworthy. (If you wire real coverage data later, prefer it over this.)
     def self._has_matching_test(rel_path)
       require 'set'
 
       name = File.basename(rel_path, '.rb')
-      # Parent directory name (e.g. "database" from "database/sqlite3_adapter.rb")
-      parent_dir = File.dirname(rel_path)
-      parent_module = (parent_dir != '.' && !parent_dir.empty?) ? File.basename(parent_dir) : ''
-
-      # Stage 1: Filename matching — name_spec, name_test, test_name patterns
-      test_dirs = ['spec', 'spec/tina4', 'test', 'tests']
-      test_dirs.each do |td|
-        patterns = [
-          "#{td}/#{name}_spec.rb",
-          "#{td}/#{name}s_spec.rb",
-          "#{td}/#{name}_test.rb",
-          "#{td}/test_#{name}.rb",
-        ]
-        # Also check parent-named tests (spec/database_spec.rb covers database/sqlite3_adapter.rb)
-        if parent_module && !parent_module.empty? && parent_module != name
-          patterns << "#{td}/#{parent_module}_spec.rb"
-          patterns << "#{td}/#{parent_module}s_spec.rb"
-          patterns << "#{td}/#{parent_module}_test.rb"
-          patterns << "#{td}/test_#{parent_module}.rb"
-        end
-        return true if patterns.any? { |p| File.exist?(p) }
-      end
-
-      # Build a dotted/slashed require path for import matching
-      # e.g. "lib/tina4/database/sqlite3_adapter.rb" → "tina4/database/sqlite3_adapter"
-      path_without_ext = rel_path.sub(/\.rb$/, '')
-      # Strip leading lib/ prefix if present
-      require_path = path_without_ext.sub(%r{^lib/}, '')
-
-      # Build CamelCase class name from snake_case module name
-      # e.g. "sqlite3_adapter" → "Sqlite3Adapter"
-      class_name = name.split('_').map(&:capitalize).join
-
-      # Stage 2+3: Content scan — check if any spec/test file references this module
-      scan_dirs = ['spec', 'test', 'tests']
-      scan_dirs.each do |td|
-        next unless Dir.exist?(td)
-        Dir.glob(File.join(td, '**', '*.rb')).each do |test_file|
-          content = begin
-            File.read(test_file, encoding: 'utf-8')
-          rescue StandardError
-            next
+
+      # Require path WITHOUT extension, leading lib/ stripped:
+      # "lib/tina4/database/sqlite.rb" -> "tina4/database/sqlite"
+      require_path = rel_path.sub(/\.rb$/, '').sub(%r{^lib/}, '')
+
+      # Constants (classes/modules) DEFINED at the top level of this file — a
+      # spec referencing one of them genuinely exercises this file. Names only,
+      # distinctive (>3 chars, leading uppercase); bare module-name words and
+      # guessed CamelCase are too loose to trust.
+      defined_symbols = _defined_constants(rel_path)
+
+      # Search roots: CWD plus (in framework-fallback mode) the repo root that
+      # owns spec/ — walk up from the scan root to find it.
+      search_roots = ['.']
+      if @last_scan_root && !@last_scan_root.empty?
+        scan_root = @last_scan_root
+        5.times do
+          if %w[spec test tests].any? { |d| Dir.exist?(File.join(scan_root, d)) }
+            search_roots << scan_root
+            break
+          end
+          parent = File.dirname(scan_root)
+          break if parent == scan_root
+          scan_root = parent
+        end
+      end
+      search_roots.uniq!
+
+      test_dirs = %w[spec test tests]
+
+      # Stage 1: a dedicated spec/test FILE named for THIS module (no parent-dir
+      # blanket match).
+      filename_patterns = [
+        "#{name}_spec.rb",
+        "#{name}s_spec.rb",
+        "#{name}_test.rb",
+        "test_#{name}.rb",
+      ]
+      search_roots.each do |root|
+        test_dirs.each do |td|
+          filename_patterns.each do |fn|
+            return true if File.exist?(File.join(root, td, fn))
+          end
+        end
+      end
+
+      # Stage 2: a spec that actually REQUIRES this module (precise — matched by
+      # the require target's basename / tail of the require path), or references
+      # a constant defined in it. NO bare word-of-the-module-name match.
+      require_regexps = []
+      unless require_path.empty?
+        # require "…/<module>" or require_relative "…/<module>" — match the
+        # require string ending in this file's require path or basename.
+        rp = Regexp.escape(require_path)
+        nm = Regexp.escape(name)
+        require_regexps << /(?:require|require_relative)\s+['"][^'"]*#{rp}['"]/
+        require_regexps << %r{(?:require|require_relative)\s+['"][^'"]*/#{nm}['"]}
+      end
+      unless defined_symbols.empty?
+        sym_alt = defined_symbols.map { |s| Regexp.escape(s) }.join('|')
+        require_regexps << /\b(?:#{sym_alt})\b/
+      end
+
+      return false if require_regexps.empty?
+
+      search_roots.each do |root|
+        test_dirs.each do |td|
+          dir = File.join(root, td)
+          next unless Dir.exist?(dir)
+          Dir.glob(File.join(dir, '**', '*.rb')).each do |test_file|
+            content = begin
+              File.read(test_file, encoding: 'utf-8')
+            rescue StandardError
+              next
+            end
+            return true if require_regexps.any? { |re| content.match?(re) }
           end
-          # Stage 2: require/require_relative path matching
-          return true if !require_path.empty? && content.include?(require_path)
-          # Stage 3: class name or module name mention
-          return true if content.match?(/\b#{Regexp.escape(class_name)}\b/)
-          return true if content.match?(/\b#{Regexp.escape(name)}\b/i)
         end
       end
 
       false
     end
 
+    # Top-level class/module names defined in the file at rel_path (resolved
+    # against the last scan root when present). Distinctive names only:
+    # leading-uppercase, longer than 2 chars — so genuine 3-char constants like
+    # ORM (orm.rb) and API (api.rb), which specs reference as `Tina4::ORM` /
+    # `Tina4::API`, are detected as tested instead of being mislabelled
+    # untested. (Was > 3, which silently excluded every 3-char constant.)
+    def self._defined_constants(rel_path)
+      src_file = if @last_scan_root && !@last_scan_root.empty? && !File.exist?(rel_path)
+                   File.join(@last_scan_root, rel_path)
+                 else
+                   rel_path
+                 end
+      symbols = Set.new
+      content = begin
+        File.read(src_file, encoding: 'utf-8')
+      rescue StandardError
+        return symbols
+      end
+      content.each_line do |line|
+        stripped = line.strip
+        m = stripped.match(/\A(?:class|module)\s+([A-Z][A-Za-z0-9_]*)/)
+        next unless m
+        const = m[1]
+        symbols.add(const) if const.length > 2
+      end
+      symbols
+    end
+
     def self._files_hash(root)
       md5 = Digest::MD5.new
       root_path = Pathname.new(root)
@@ -511,8 +705,61 @@ module Tina4
       imports
     end
 
-    def self._extract_functions(source, tokens, lines)
+    # Replace the CONTENT of Ruby string literals, regex literals, and comments
+    # with neutral spaces — keeping every line's length and the line count
+    # identical to the original — so decision-point keywords and method-shaped
+    # text that live INSIDE strings/comments are never miscounted. Returns an
+    # array of cleaned lines (chomped) aligned 1:1 with the original lines.
+    #
+    # Ruby's own lexer (Ripper) does the hard parsing: it tags string/heredoc/
+    # regex bodies as :on_tstring_content (and :on_comment, :on_embdoc — the
+    # =begin/=end block-comment body), which we blank out positionally. The
+    # surrounding code structure (def/if/end keywords, operators) is left intact.
+    NOISE_TOKEN_TYPES = %i[
+      on_tstring_content on_comment on_embdoc on_embdoc_beg on_embdoc_end
+    ].freeze
+
+    def self._clean_source(source)
+      lines = source.lines.map(&:chomp)
+      # Mutable per-line character buffers we can blank out by column range.
+      buffers = lines.map(&:dup)
+
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines
+      end
+
+      tokens.each do |(pos, type, token)|
+        next unless NOISE_TOKEN_TYPES.include?(type)
+
+        row = pos[0] - 1
+        col = pos[1]
+        # A noise token may span multiple physical lines (heredocs, block
+        # comments, multi-line strings). Blank each covered line segment.
+        token.to_s.each_line.with_index do |seg, offset|
+          line_idx = row + offset
+          next if line_idx.negative? || line_idx >= buffers.length
+
+          buf = buffers[line_idx]
+          # On the token's first line the content starts at `col`; on
+          # continuation lines it starts at column 0.
+          start = offset.zero? ? col : 0
+          seg_len = seg.chomp.length
+          stop = [start + seg_len, buf.length].min
+          (start...stop).each { |c| buf[c] = ' ' } if stop > start
+        end
+      end
+
+      buffers
+    end
+
+    def self._extract_functions(source, _tokens, _lines)
       functions = []
+      # Operate on a neutralised copy: string/regex/comment CONTENT is blanked
+      # so keywords inside them are never read as real code (line numbers, line
+      # count and column widths are preserved).
+      lines = _clean_source(source)
       # Track class/module nesting for method names
       context_stack = []
       i = 0
@@ -527,7 +774,8 @@ module Tina4
           context_stack.push(class_name) unless class_name.empty?
         end
 
-        # Detect method definitions
+        # Detect method definitions — require a real `def ` declaration so a
+        # `def`-shaped substring inside a (now-blanked) string is never a method.
         if stripped.match?(/\Adef\s+/)
           method_match = stripped.match(/\Adef\s+(self\.)?(\S+?)(\(.*\))?\s*$/)
           if method_match
@@ -588,43 +836,73 @@ module Tina4
       functions
     end
 
+    # Keywords that ALWAYS open a block needing a matching `end`.
+    BLOCK_OPENERS = %w[def class module begin case].freeze
+    # Keywords that open a block ONLY in statement-leading position; in trailing
+    # position they are modifiers (`return x if y`) and need no `end`.
+    CONDITIONAL_OPENERS = %w[if unless while until for].freeze
+
+    # Find the line index where the method that starts at `start_index` ends.
+    #
+    # Token-driven (Ripper) so it is immune to the line-regex footguns that made
+    # this over-run to end-of-file (CC 496 on tiny methods):
+    #   * `self.class` — `class` after a `.` is an identifier, not a block opener
+    #     (Ripper tags it :on_ident), so it no longer bumps depth.
+    #   * modifier `if/unless/while/until/for` (`return x if y`) — only counted
+    #     as an opener in statement-LEADING position (first real token of a
+    #     statement), never trailing.
+    #   * `lines` are already string/comment-cleaned, so keywords inside string
+    #     bodies are gone too.
+    # Falls back to the last line only if no matching `end` is found.
     def self._find_method_end(lines, start_index)
-      depth = 0
-      i = start_index
-      base_indent = lines[i].length - lines[i].lstrip.length
+      source = lines[start_index..].join("\n")
+      tokens = begin
+        Ripper.lex(source)
+      rescue StandardError
+        return lines.length - 1
+      end
 
-      while i < lines.length
-        stripped = lines[i].strip
+      depth = 0
+      # A keyword is a block opener only when it leads a statement. Track that:
+      # we are at statement start initially and right after a newline / `;`.
+      at_statement_start = true
+      seen_opener = false
 
-        unless stripped.empty? || stripped.start_with?('#')
-          # Count block openers
-          if stripped.match?(/\b(def|class|module|if|unless|case|while|until|for|begin|do)\b/) &&
-             !stripped.match?(/\bend\b/) &&
-             !stripped.end_with?(' if ', ' unless ', ' while ', ' until ') &&
-             !(stripped.match?(/\bif\b|\bunless\b|\bwhile\b|\buntil\b/) && i != start_index && _is_modifier?(stripped))
+      tokens.each do |(pos, type, token)|
+        case type
+        when :on_kw
+          if BLOCK_OPENERS.include?(token)
             depth += 1
-          end
-
-          if stripped == 'end' || stripped.start_with?('end ') || stripped.start_with?('end;')
+            seen_opener = true
+          elsif token == 'do'
+            depth += 1
+            seen_opener = true
+          elsif CONDITIONAL_OPENERS.include?(token)
+            # Leading => real block opener; trailing => modifier (no end).
+            if at_statement_start
+              depth += 1
+              seen_opener = true
+            end
+          elsif token == 'end'
             depth -= 1
-            return i if depth <= 0
+            if seen_opener && depth <= 0
+              return start_index + (pos[0] - 1)
+            end
           end
+          at_statement_start = false
+        when :on_nl, :on_ignored_nl, :on_semicolon
+          at_statement_start = true
+        when :on_sp, :on_comment, :on_embdoc, :on_embdoc_beg, :on_embdoc_end
+          # whitespace/comments don't change statement-start state
+        else
+          at_statement_start = false
         end
-
-        i += 1
       end
 
       # If we never found the end, return last line
       lines.length - 1
     end
 
-    def self._is_modifier?(line)
-      # A rough check: if the keyword is not at the start of the meaningful content,
-      # it's likely a modifier (e.g., "return x if condition")
-      stripped = line.strip
-      !stripped.match?(/\A(if|unless|while|until)\b/)
-    end
-
     def self._cyclomatic_complexity_from_source(source)
       cc = 1