tina4ruby 3.13.37 → 3.13.38

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,137 @@ 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 3 chars.
+    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 > 3
+      end
+      symbols
+    end
+
     def self._files_hash(root)
       md5 = Digest::MD5.new
       root_path = Pathname.new(root)

data/lib/tina4/middleware.rb

@@ -41,24 +41,44 @@ module Tina4
         @global_middleware = []
       end
 
-      # Run all "before" hooks: block-based handlers, then class-based before_* methods.
+      # Run all "before" hooks: block-based handlers, then class-based before_*
+      # methods (in definition order).
       #
       # Signature matches Python/PHP/Node orchestrators: pass the list of
       # middleware classes explicitly.
       #
-      # Returns [request, response] on success, or false to halt the request.
+      # M2 — visible-but-resilient: every before_* call is wrapped so a THROW
+      # never crashes the worker. On a throw the error is LOGGED and the
+      # response becomes a clean 500 ({"error":"Internal Server Error",
+      # "status":500}), then processing halts (handler skipped) — deterministic,
+      # never an unhandled exception. A before_* that sets status >= 400 also
+      # halts (the existing 4xx short-circuit). after_* still run on either
+      # halt path (see the dispatcher / #run_after docstring).
+      #
+      # Returns true on success, or false to halt the request (handler skipped).
       def run_before(middleware_classes, request, response)
         # 1. Block-based before handlers (pattern-matched)
         before_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
-          result = entry[:handler].call(request, response)
+
+          begin
+            result = entry[:handler].call(request, response)
+          rescue StandardError, ScriptError => error
+            middleware_500(response, "before handler", error)
+            return false
+          end
           return false if result == false
         end
 
-        # 2. Class-based middleware: call every before_* method
+        # 2. Class-based middleware: call every before_* method (definition order)
         middleware_classes.each do |klass|
           before_methods_for(klass).each do |method_name|
-            result = klass.send(method_name, request, response)
+            begin
+              result = klass.send(method_name, request, response)
+            rescue StandardError, ScriptError => error
+              middleware_500(response, "#{class_label(klass)}.#{method_name}", error)
+              return false
+            end
             # Support returning [request, response] (Python convention) or false to halt
             if result == false
               return false
@@ -73,21 +93,42 @@ module Tina4
         true
       end
 
-      # Run all "after" hooks: block-based handlers, then class-based after_* methods.
+      # Run all "after" hooks: block-based handlers, then class-based after_*
+      # methods (in definition order).
       #
       # Signature matches Python/PHP/Node orchestrators: pass the list of
       # middleware classes explicitly.
+      #
+      # AFTER-ON-4xx RULE (M2, documented + consistent across all 4 frameworks):
+      # after_* ALWAYS run even when a before_* short-circuited with status >= 400
+      # and the handler was skipped — so they can still add headers / logging.
+      # The dispatcher calls #run_after unconditionally after the before/handler
+      # block (including on the 4xx / throw halt path).
+      #
+      # M2 — every after_* call is wrapped: a THROW is LOGGED and turns the
+      # response into a clean 500, then the REMAINING after_* still run (they
+      # may add headers/logging). Never an unhandled crash.
       def run_after(middleware_classes, request, response)
         # 1. Block-based after handlers (pattern-matched)
         after_handlers.each do |entry|
           next unless matches_pattern?(request.path, entry[:pattern])
-          entry[:handler].call(request, response)
+
+          begin
+            entry[:handler].call(request, response)
+          rescue StandardError, ScriptError => error
+            middleware_500(response, "after handler", error)
+          end
         end
 
-        # 2. Class-based middleware: call every after_* method
+        # 2. Class-based middleware: call every after_* method (definition order)
         middleware_classes.each do |klass|
           after_methods_for(klass).each do |method_name|
-            result = klass.send(method_name, request, response)
+            begin
+              result = klass.send(method_name, request, response)
+            rescue StandardError, ScriptError => error
+              middleware_500(response, "#{class_label(klass)}.#{method_name}", error)
+              next
+            end
             if result.is_a?(Array) && result.length == 2
               request, response = result
             end
@@ -95,8 +136,38 @@ module Tina4
         end
       end
 
+      # Deterministic clean 500 for a middleware that threw. Logs the cause
+      # (NEVER silent) then sets the response to the canonical error shape —
+      # byte-identical to the Python master ({"error":"Internal Server Error",
+      # "status":500} + status 500). Returns the response for chaining.
+      def middleware_500(response, label, error)
+        begin
+          Tina4::Log.error(
+            "Middleware #{label} raised #{error.class.name}: #{error.message}"
+          )
+        rescue StandardError
+          begin
+            $stderr.puts("Middleware #{label} raised #{error.class.name}: #{error.message}")
+            $stderr.flush
+          rescue StandardError
+            # never let logging break the worker
+          end
+        end
+        response.json({ error: "Internal Server Error", status: 500 }, 500)
+      end
+
       private
 
+      # Human-readable label for a middleware (class name, or the class of an
+      # instance) used in the logged 500 message.
+      def class_label(klass)
+        if klass.is_a?(Class) || klass.is_a?(Module)
+          klass.name || klass.to_s
+        else
+          klass.class.name || klass.class.to_s
+        end
+      end
+
       def matches_pattern?(path, pattern)
         return true if pattern.nil?
         case pattern
@@ -109,14 +180,66 @@ module Tina4
         end
       end
 
-      # Collect all public class methods matching before_*
+      # Collect all class methods matching before_* in DEFINITION order.
       def before_methods_for(klass)
-        klass.methods(false).select { |m| m.to_s.start_with?("before_") }.sort
+        discover_methods(klass, "before_")
       end
 
-      # Collect all public class methods matching after_*
+      # Collect all class methods matching after_* in DEFINITION order.
       def after_methods_for(klass)
-        klass.methods(false).select { |m| m.to_s.start_with?("after_") }.sort
+        discover_methods(klass, "after_")
+      end
+
+      # ----------------------------------------------------------------------
+      # MIDDLEWARE ORDERING (M1) — within a class, before_*/after_* methods run
+      # in SOURCE-DEFINITION order, NOT alphabetical. Cross-class order is the
+      # natural iteration of the registered middleware list (registration
+      # order). before_* run before the handler, after_* after.
+      #
+      # WHY source line numbers, not instance_methods(false): in Ruby/PRISM
+      # `instance_methods(false)` is NOT a reliable definition-order report —
+      # once a method NAME (symbol) has been defined on any other class first,
+      # that name can sort ahead in a later class's list. So we sort the
+      # matching methods by their `source_location` line number, which IS the
+      # true source-definition order and is immune to the symbol-table quirk.
+      # (Methods with no source_location — e.g. C-defined — sort to the front
+      # deterministically by name.) We walk the ancestry base→derived so
+      # inherited middleware methods run before a subclass's own, de-duping
+      # overrides to their first (base) position. Mirrors the Python master's
+      # Middleware._discover_methods MRO walk (which leans on __dict__ insertion
+      # order — the equivalent of source-definition order).
+      def discover_methods(klass, prefix)
+        target = klass.is_a?(Class) || klass.is_a?(Module) ? klass.singleton_class : klass.class
+        seen = {}
+        names = []
+        target.ancestors.reverse_each do |ancestor|
+          matched = begin
+                      ancestor.instance_methods(false).select do |name|
+                        name.to_s.start_with?(prefix) &&
+                          !seen.key?(name) &&
+                          klass.respond_to?(name)
+                      end
+                    rescue StandardError
+                      []
+                    end
+
+          ordered = matched.sort_by.with_index do |name, idx|
+            line = begin
+                     loc = ancestor.instance_method(name).source_location
+                     loc ? loc[1] : -1
+                   rescue StandardError
+                     -1
+                   end
+            # Tie-break on the symbol-table index so the result is total/stable.
+            [line, idx]
+          end
+
+          ordered.each do |name|
+            seen[name] = true
+            names << name
+          end
+        end
+        names
       end
     end
   end

data/lib/tina4/migration.rb

@@ -356,10 +356,12 @@ module Tina4
           Tina4::Log.info("Migration #{File.basename(file)}: #{skip_reason}")
           next
         end
-        result = @db.execute(stmt)
-        if result == false
-          raise RuntimeError, @db.get_error || "SQL execution failed: #{stmt}"
-        end
+        # db.execute() now RAISES on a SQL error (it no longer returns false),
+        # so a bad statement throws straight up to run_migration's rescue, which
+        # records the migration as failed and surfaces the error. The old
+        # "if result == false: raise" check is dead — a plain execute carries
+        # the same failure semantics.
+        @db.execute(stmt)
       end
     end
 

data/lib/tina4/orm.rb

@@ -425,17 +425,20 @@ module Tina4
         translator_engine = %w[postgres postgresql].include?(engine) ? "postgresql" : engine
         sql = SQLTranslator.auto_increment_syntax(sql, translator_engine)
 
-        # Don't claim success when the DDL failed. db.execute() swallows the
-        # driver error into get_error() and returns false, so a bad type (or
-        # any DDL error) used to leave create_table returning true while no
-        # table was actually created.
-        ok = db.execute(sql)
-        db.commit
-        if ok == false
-          Tina4::Log.error("create_table failed for #{table_name}: #{db.get_error}", { sql: sql })
-          return false
+        # Don't claim success when the DDL failed. db.execute() now RAISES on a
+        # SQL error (it no longer swallows it into get_error() and returns
+        # false), so a bad type (or any DDL error) surfaces here as an
+        # exception. create_table keeps its documented bool contract: catch the
+        # raise, log the cause, and return false so callers that test the return
+        # still see a clean failure instead of a thrown error.
+        begin
+          db.execute(sql)
+          db.commit
+          true
+        rescue => e
+          Tina4::Log.error("create_table failed for #{table_name}: #{db.get_error || e.message}", { sql: sql })
+          false
         end
-        true
       end
 
       def scope(name, filter_sql, params = [])

data/lib/tina4/rack_app.rb

@@ -351,9 +351,12 @@ module Tina4
       env["tina4.request"] = request  # Store for session save after response
       response = Tina4::Response.new
 
-      # Run global middleware (block-based + class-based before_* methods)
+      # Run global middleware (block-based + class-based before_* methods).
+      # M2 — AFTER-ON-4xx RULE: when a before_* short-circuits (4xx/skip) or
+      # throws (clean 500), the after-pass STILL runs so after_* can add
+      # headers/logging — consistent across all 4 frameworks.
       unless Tina4::Middleware.run_before(Tina4::Middleware.global_middleware, request, response)
-        # Middleware halted the request -- return whatever response was set
+        Tina4::Middleware.run_after(Tina4::Middleware.global_middleware, request, response)
         return response.to_rack
       end
 
@@ -885,18 +888,23 @@ module Tina4
       # Wire the route handler into the WebSocket engine events
       handler = ws_route.handler
 
-      # Create a dedicated WebSocket engine for this route so handlers stay isolated
+      # Create a dedicated WebSocket *event* engine for this route so each
+      # upgrade keeps its own isolated open/message/close handlers (the engine's
+      # on() appends handlers, so a single shared event engine would cross-wire
+      # routes).
       ws = Tina4::WebSocket.new
 
-      # The dev-reload channel is held by a process-wide shared manager so a
-      # broadcast from POST /__dev/api/reload reaches every browser, not just
-      # the connections of this one isolated per-socket engine. Mirrors
-      # Python's single _ws_manager keyed on the /__dev_reload path.
+      # The connection itself is OWNED by a process-wide shared manager so that
+      # broadcasts, rooms, the multi-instance backplane and the idle reaper span
+      # every route's connections — not just this one per-socket event engine.
+      # Mirrors Python's single WebSocketManager. The dev-reload channel uses its
+      # own shared manager (Tina4::DevReload) so POST /__dev/api/reload reaches
+      # every browser.
       dev_reload = ws_route.path == "/__dev_reload"
+      manager = dev_reload ? Tina4::DevReload.manager : @websocket_engine
 
       ws.on(:open) do |connection|
         connection.params = ws_params
-        Tina4::DevReload.add(connection) if dev_reload
         handler.call(connection, :open, nil)
       end
 
@@ -905,7 +913,6 @@ module Tina4
       end
 
       ws.on(:close) do |connection|
-        Tina4::DevReload.remove(connection) if dev_reload
         handler.call(connection, :close, nil)
       end
 
@@ -913,7 +920,7 @@ module Tina4
         Tina4::Log.error("WebSocket error on #{ws_route.path}: #{error.message}")
       end
 
-      ws.handle_upgrade(env, socket)
+      ws.handle_upgrade(env, socket, manager: manager)
 
       # Return async response (-1 signals Rack the response is handled via hijack)
       [-1, {}, []]