hubbado-log 1.3.0 → 1.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 49c303fe323be43f901ed8ef3958b87c79296af3a15efb11c9efb8a9b57156aa
-  data.tar.gz: 97bc2f947b3a4fc0cfd1845c34d722d6608cf36c1daf853334d3b3b03c4171b5
+  metadata.gz: 99367c1895c07697aa0e83dc1e068f35cf2052d75dc6c471610b47099f27fd7f
+  data.tar.gz: 58a148cfa36ea3709a2c36fbb228f089d3b176476d27ede4a74ec26a651bdf12
 SHA512:
-  metadata.gz: fde7c3bf0995e34348f47a8441df1b95cf9505c909b08bac8fcc409f994ce8c8eb28cb05343e24b4066977a804434ced09cad3fb36e75908e375d3bddbc81304
-  data.tar.gz: 4f4cae84446c3d1bdf8a9ebb2b986f82a558c623af90a3278c62fa67ee8a23a55163129efc787758b5434faf101346e15187c9f112007333b7295cb26cf3648f
+  metadata.gz: 5a53b16af1babaa5c90125bfddec34a02c5256661004833a63b5b54066a914bf764d2c3c738d0a0d2e556d4bd9ef86d96d7e40419e7acd810f2fb7ca4fe58788
+  data.tar.gz: 6f77c77d30c8a1ef7f89b2b73c8e09585aa3f39d6dd5d9046796220f699f2926c31debd5fb5b8f514e06c7a2fb66e2b5e20be6cf7f86b95e56bba6218a2ef5e5

data/ChangeLog.md

@@ -4,6 +4,79 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+# [1.4.1 - 2026-08-16]
+## Fixed
+- A subclass of `Hubbado::Log` can be used as a dependency. It answered `nil`
+  from `config` and raised `undefined method 'loggers' for nil` on its first
+  line, because the configuration was held in a class-level instance variable
+  and those are not inherited.
+
+  ```ruby
+  module Messaging
+    class Log < Hubbado::Log; end
+  end
+
+  class Handler
+    include Messaging::Log::Dependency
+  end
+  ```
+
+  The configuration is the process's now, and holds the handlers built from it,
+  so every class that writes reads the one a command configured and one
+  reconfiguration reaches all of them.
+
+# [1.4.0 - 2026-08-16]
+## Added
+- A substitute for a logger. `Controls::Logger.example` returns one, and a spec
+  assigns it where a class's logger goes:
+
+  ```ruby
+  instance.logger = Hubbado::Log::Controls::Logger.example
+
+  instance.()
+
+  assert instance.logger.logged?(:error)
+  ```
+
+  It records what it was told rather than writing, so no handler is involved and
+  neither the level nor the tag list decides what a spec can read back.
+
+  Three questions, each taking an optional severity, and each answering in the
+  terms its name promises:
+
+  | Call | Answers |
+  |---|---|
+  | `logged?(:warn)` | whether anything was written at that severity |
+  | `messages(:warn)` | what it said — the message strings |
+  | `logged(:warn)` | everything about what it said — `severity`, `message`, `data` |
+
+  `messages` and `logged?` are both derived from `logged`, so the three cannot
+  disagree about what counts as written at a severity.
+
+  A severity reaches a logger two ways — as the generated method, or as `#log`'s
+  first argument — and both answer the same question, compared as symbols.
+
+- `evt-subst_attr` as a runtime dependency. The substitute is a mimic of `Logger`
+  extended with `Logger::Substitute`, so it answers `is_a?(Logger)` for a class
+  that checks, and gains any method `Logger` gains.
+
+## Deprecated
+- `Controls::LogHandler` as the way a consumer reads back what a class logged.
+  It builds a real `Logger` and then passes `level: :trace` and `tags: Tags::ALL`
+  to switch off the filtering it just built — which is a substitute, reached the
+  long way round. Use `Controls::Logger.example`. The handler control stays for
+  what it is good at: specs where a handler receiving, or not receiving, a
+  message is the subject, as `'A message the filter left out'` is.
+
+## Changed
+- `Controls::LogHandler` names `Log::Logger` where it said `Logger`. With
+  `Controls::Logger` defined, a bare `Logger` inside `Controls` resolves to the
+  control rather than to the class.
+
+## Compatibility
+Nothing that exists breaks. `Controls::LogHandler` keeps `.attach`, `.logger`,
+`messages`, `logged?`, `reset` and the attributes, unchanged.
+
 # [1.3.0 - 2026-08-15]
 ## Added
 - Tags, a second filtering axis beside the level. A message names its concern

data/README.md

@@ -18,6 +18,36 @@ Or install it yourself as:
 
     $ gem install hubbado-log
 
+## A class's own logger
+
+A class that includes the dependency module gets a `logger` writing under its own name:
+
+```ruby
+class MyService
+  include Hubbado::Log::Dependency
+
+  def call
+    logger.info('Did the thing')
+  end
+end
+```
+
+A subclass carries a dependency module of its own, so a library or a component can name where
+its classes take their logger from:
+
+```ruby
+module Messaging
+  class Log < Hubbado::Log; end
+end
+
+class Handler
+  include Messaging::Log::Dependency
+end
+```
+
+Either way the logger writes through the handlers the process was configured with, at the level
+and tags it was configured for.
+
 ## Level
 
 A message below the level reaches no handler.
@@ -111,6 +141,67 @@ knowing before adopting tags:
 list decides for both, and an application whose messages are all untagged goes silent unless the
 list contains `_untagged`.
 
+## Reading back what a class logged
+
+A spec assigns a substitute where the class's logger goes, and then asks what the class said:
+
+```ruby
+require 'hubbado/log/controls'
+
+instance.logger = Hubbado::Log::Controls::Logger.example
+
+instance.()
+
+assert instance.logger.logged?(:error)
+```
+
+For a class handed a logger rather than carrying one — the shape a CLI usually takes — it is the
+same object, passed in:
+
+```ruby
+logger = Hubbado::Log::Controls::Logger.example
+
+CLI.run(argv, logger: logger)
+
+assert logger.logged?(:error)
+```
+
+It records what it was told rather than writing, so no handler is involved and neither the
+configured level nor `LOG_TAGS` decides what can be read back.
+
+Three questions, each taking an optional severity:
+
+| Call | Answers |
+|---|---|
+| `logged?` / `logged?(:warn)` | whether anything was written, at all or at that severity |
+| `messages` / `messages(:warn)` | what it said — the message strings, in order |
+| `logged` / `logged(:warn)` | everything about what it said |
+
+`logged` answers with entries carrying `severity`, `message` and `data`, for the assertion that
+needs more than the text:
+
+```ruby
+assert logger.logged(:error).first.data.equal?(exception)
+```
+
+`messages` and `logged?` are both derived from `logged`, so the three cannot disagree about what
+counts as written at a severity.
+
+A severity reaches a logger two ways — `logger.warn('…')` names it as the method,
+`logger.log(:warn, '…')` as an argument — and both answer the same question, compared as symbols.
+
+The substitute is a mimic of `Logger`, so it answers `is_a?(Hubbado::Log::Logger)` for a class
+that checks, and gains any method `Logger` gains.
+
+Prefer `logged?` to reaching into `messages` where it will do. That a failure was reported is
+usually the contract; the wording of the line usually is not.
+
+### Testing a handler
+
+`Controls::LogHandler` is for specs where a handler receiving — or not receiving — a message is
+itself the subject, which in practice means this gem's own tests of level and tag filtering. A
+consumer asserting that its class logged something wants the substitute above.
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/hubbado-log.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name = "hubbado-log"
-  s.version = "1.3.0"
+  s.version = "1.4.1"
   s.summary = "Lightweight pluggable logging system"
 
   s.authors = ["Hubbado Devs"]
@@ -25,6 +25,7 @@ Gem::Specification.new do |s|
   s.required_ruby_version = '>= 3.2'
 
   s.add_runtime_dependency 'evt-dependency'
+  s.add_runtime_dependency 'evt-subst_attr'
 
   s.add_development_dependency "debug"
   s.add_development_dependency "hubbado-style"

data/lib/hubbado/log/configuration.rb

@@ -5,16 +5,45 @@ module Hubbado
       # for a human watching one run without it also reaching every unattended log.
       DEFAULT_LEVEL = :info
 
-      attr_accessor :loggers
+      attr_reader :loggers
       attr_reader :level
       attr_reader :tags
 
+      # The configuration is the process's rather than a class's, so a subclass of Log reads the
+      # one a command wrote and there is a single set of handlers to build from it.
+      #
+      # The one place the environment is read. A command names its level and tags here or not at
+      # all, and everything downstream is handed the value rather than the variable.
+      def self.instance
+        @instance ||= new(level: ENV[LEVEL_VARIABLE], tags: ENV[TAGS_VARIABLE])
+      end
+
       def initialize(level: nil, tags: nil)
-        @loggers = []
+        self.loggers = []
         self.level = level || DEFAULT_LEVEL
         self.tags = tags
       end
 
+      # Whatever the block leaves behind is what the process is configured for, and the handlers
+      # are built again from it. Named here rather than left to the caller, because a block is
+      # free to mutate the list of loggers in place and never reach the writer below.
+      def change
+        yield self
+
+        @log_handlers = nil
+      end
+
+      # The handlers themselves, one set for the process. A handler holds what it has been told,
+      # so a second set built somewhere else would be a second place to read it back from.
+      def log_handlers
+        @log_handlers ||= loggers.map(&:new)
+      end
+
+      def loggers=(value)
+        @log_handlers = nil
+        @loggers = value
+      end
+
       # Takes the LOG_TAGS string as readily as a list, so nothing upstream has to know the
       # syntax in order to hand a value in.
       def tags=(value)

data/lib/hubbado/log/controls/log_handler.rb

@@ -20,7 +20,7 @@ module Hubbado
           end
 
           new.tap do |handler|
-            instance.logger = Logger.new(logger.subject, [handler], level: level, tags: tags)
+            instance.logger = Log::Logger.new(logger.subject, [handler], level: level, tags: tags)
           end
         end
 
@@ -28,7 +28,7 @@ module Hubbado
         def self.logger(subject = Subject.example, level: :trace, tags: Tags::ALL)
           handler = new
 
-          [handler, Logger.new(subject, [handler], level: level, tags: tags)]
+          [handler, Log::Logger.new(subject, [handler], level: level, tags: tags)]
         end
 
         def log(subject, severity, message, data = nil, stacktrace = nil)

data/lib/hubbado/log/controls/logger.rb

@@ -0,0 +1,16 @@
+require 'subst_attr'
+
+module Hubbado
+  class Log
+    module Controls
+      module Logger
+        # A logger a spec assigns in place of a class's own, and then asks what the class said.
+        # Named here because the substitute is reached by building a mimic of Log::Logger, which
+        # is machinery a spec should not have to name.
+        def self.example
+          SubstAttr::Substitute.build(Log::Logger)
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log/controls.rb

@@ -4,3 +4,4 @@ require_relative 'controls/message'
 require_relative 'controls/subject'
 
 require_relative 'controls/log_handler'
+require_relative 'controls/logger'

data/lib/hubbado/log/log.rb

@@ -11,22 +11,16 @@ module Hubbado
     LEVEL_VARIABLE = "LOG_LEVEL".freeze
     TAGS_VARIABLE = "LOG_TAGS".freeze
 
-    # The one place the environment is read. A command names its level and tags here or not at
-    # all, and everything downstream is handed the value rather than the variable.
-    @config = Configuration.new(level: ENV[LEVEL_VARIABLE], tags: ENV[TAGS_VARIABLE])
-
     class << self
-      attr_reader :config
-
-      def configuration
-        yield @config
+      # Held by the configuration itself rather than here, because a class-level instance
+      # variable is not inherited: a subclass asking this class would answer nil.
+      def config = Configuration.instance
 
-        @loggers = nil
+      def configuration(&block)
+        config.change(&block)
       end
 
-      def loggers
-        @loggers ||= config.loggers.map(&:new)
-      end
+      def loggers = config.log_handlers
 
       def logger
         @logger = Logger.new('', loggers)

data/lib/hubbado/log/logger/substitute.rb

@@ -0,0 +1,50 @@
+module Hubbado
+  class Log
+    class Logger
+      # What a logger was told rather than what it wrote. Extended onto a mimic of Logger, so a
+      # class under test is handed something that answers as a logger and keeps what it was given.
+      module Substitute
+        Entry = Data.define(:severity, :message, :data)
+
+        # Everything about what a class said, in order. Named with a severity, only what it said
+        # at that one.
+        #
+        # A severity reaches a logger two ways: as the method, from the generated severity
+        # methods, or as #log's first argument. Both are compared as symbols, because #log takes
+        # a String as readily and passes on what it was given.
+        def logged(severity = nil)
+          entries = invocations.map { |invocation| entry(invocation) }
+
+          return entries if severity.nil?
+
+          entries.select { |entry| entry.severity == severity.to_s.to_sym }
+        end
+
+        # What a class said, where #logged is everything about it.
+        def messages(severity = nil) = logged(severity).map(&:message)
+
+        # Whether, where #logged and #messages ask what. Without a severity, whether anything was
+        # written at all.
+        def logged?(severity = nil) = !logged(severity).empty?
+
+        private
+
+        def entry(invocation)
+          arguments = invocation.arguments
+
+          Entry.new(
+            severity: severity(invocation).to_s.to_sym,
+            message: arguments[:msg],
+            data: arguments[:data]
+          )
+        end
+
+        def severity(invocation)
+          return invocation.arguments.fetch(:severity) if invocation.method_name == :log
+
+          invocation.method_name
+        end
+      end
+    end
+  end
+end

data/lib/hubbado/log.rb

@@ -3,6 +3,7 @@ require "hubbado/log/tags"
 require "hubbado/log/configuration"
 require "hubbado/log/log"
 require "hubbado/log/logger"
+require "hubbado/log/logger/substitute"
 require "hubbado/log/log_handler"
 
 module Hubbado

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hubbado-log
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.1
 platform: ruby
 authors:
 - Hubbado Devs
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: evt-subst_attr
+  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: debug
   requirement: !ruby/object:Gem::Requirement
@@ -81,11 +95,13 @@ files:
 - lib/hubbado/log/controls/data.rb
 - lib/hubbado/log/controls/exception.rb
 - lib/hubbado/log/controls/log_handler.rb
+- lib/hubbado/log/controls/logger.rb
 - lib/hubbado/log/controls/message.rb
 - lib/hubbado/log/controls/subject.rb
 - lib/hubbado/log/log.rb
 - lib/hubbado/log/log_handler.rb
 - lib/hubbado/log/logger.rb
+- lib/hubbado/log/logger/substitute.rb
 - lib/hubbado/log/tags.rb
 homepage: https://www.github.com/hubbado/hubbado-log
 licenses: