logaru 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3192f41c03547e6173ca0002334fc95e8ee10a5d377891a84b5b543f53dd9306
+  data.tar.gz: c05dfdb1f92db1cb6518c3850360cc0a4a8f049e4e32bdd9a18404f66459f9d2
+SHA512:
+  metadata.gz: f31e77c1b4b91420bc45aa4fffbacaa61995cc054a8e2fcac74fbdb06fe1a7fd2ee996302cab4e956d03bdd5f2123f5bfc75703e1784045c6c35db4c9d80ff37
+  data.tar.gz: 691e1faa39da9edb5971c8723fe1477be2749ef16853fe45c3d1491d68b51b74f7dc792ba4cba447465fea84130209c30107ea147b70d585dc84915f373a71ea

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-09-24
+
+First stable release. Requires Ruby >= 3.3 and has no runtime dependencies.
+
+### Added
+
+- `Logaru::Logger` with `debug`, `info`, `warn`, `error`, `fatal` and `unknown`, plus the generic `log(severity, message, progname:)`.
+- Level filtering: a severity is accepted as a `Logaru::Level` constant, a name or a symbol, and entries below the configured level are discarded before formatting.
+- `Logaru::Logger` writes to `$stdout` by default, to a log file (`String` or `Pathname`: parent directories created, append mode, handle reused, flushed on every write) or to any object responding to `#write`.
+- `Logaru::Logger#formatter`, `#level`, `#output` and `#device` readers, plus `#close`, which releases the file opened by the logger so it can be rotated externally — the next write reopens it.
+- `Logaru::Formatter` with a configurable pattern (`pattern:` or a block), pattern arity validation and `Logaru::Formatter::DEFAULT_PATTERN`.
+- `Logaru::Level` severities, `coerce` and `name_for`.
+- Error hierarchy under `Logaru::Error`: `InvalidFormatterError`, `InvalidLevelError`, `InvalidPatternError` and `InvalidOutputError`, all raised from `Logger.new`/`Formatter.new`.
+- Thread safety: writes, device resolution and `#close` are serialized by a mutex and the log file is opened only once, so one logger can be shared between threads.
+
+[Unreleased]: https://github.com/rpzerosixcode/logaru/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/rpzerosixcode/logaru/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rpzerosixcode
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,185 @@
+# Logaru
+
+[![CI](https://github.com/rpzerosixcode/logaru/actions/workflows/ci.yml/badge.svg)](https://github.com/rpzerosixcode/logaru/actions/workflows/ci.yml)
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D_3.3-ruby.svg)](https://www.ruby-lang.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+A Ruby library focused on clear, organized, and configurable log output.
+
+> 🇧🇷 **Made in Brazil.**
+>
+> Logaru is a Brazilian Ruby gem, developed in Brazil.
+
+## Installation
+
+Add Logaru to your Gemfile:
+
+```ruby
+gem "logaru"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install it directly:
+
+```bash
+gem install logaru
+```
+
+## Usage
+
+```ruby
+require "logaru"
+
+Logaru::VERSION # => "1.0.0"
+
+Logaru.root # => absolute path to the gem root
+```
+
+The logger supports `debug`, `info`, `warn`, `error`, `fatal`, and `unknown` messages. Levels can be configured with a `Logaru::Level` constant, a level name, or a symbol:
+
+```ruby
+logger = Logaru::Logger.new(level: :info)
+
+logger.debug("This message is ignored")
+
+logger.info("Application started", progname: "web")
+
+logger.error("An unexpected error occurred")
+```
+
+Pass `file:` to append messages to a file. Log files are opened on the first write, reused afterwards, and their parent directories are created automatically:
+
+```ruby
+logger = Logaru::Logger.new(file: "log/application.log")
+
+logger.info("Application started")
+
+logger.output  # => "log/application.log"
+
+logger.device  # => the File object used for writing
+
+logger.close   # closes the file; it is reopened on the next write
+```
+
+A `Pathname` or any object responding to `#write` (such as `StringIO` or an already open `File`) is accepted as well. Writes are flushed by default (`sync: true`) so the file is always up to date, and the logger only closes files it opened itself — streams provided through `file:` remain the caller's responsibility.
+
+Rotating the log is left to your tooling: call `logger.close`, rename or replace the file, and the next entry reopens the path (see [Architecture](docs/ARCHITECTURE.md#log-file-lifecycle)).
+
+### Formatters
+
+Every logger builds its own `Logaru::Formatter`, so customizing the output never requires injecting one:
+
+```ruby
+logger = Logaru::Logger.new(level: :debug, file: "log/application.log") do |severity, datetime, progname, message|
+  "[#{datetime}] #{progname || "app"} #{Logaru::Level.name_for(severity).upcase}: #{message}\n"
+end
+```
+
+The same pattern can be passed as an option, and a formatter instance can still be injected to share one configuration between loggers (`formatter:` and `pattern:` are mutually exclusive):
+
+```ruby
+pattern = proc { |severity, datetime, progname, message| "#{severity} #{message}\n" }
+
+Logaru::Logger.new(pattern: pattern)
+
+formatter = Logaru::Formatter.new(pattern: pattern)
+
+Logaru::Logger.new(formatter: formatter)
+
+Logaru::Logger.new(formatter: formatter, pattern: pattern)
+
+# => Logaru::InvalidFormatterError: pass either formatter or pattern, not both
+```
+
+Formatters keep no global state, so each logger can use its own pattern. A pattern must be able to receive the four arguments (`severity`, `datetime`, `progname`, `message`); variadic patterns such as `|*arguments|` are accepted too:
+
+```ruby
+Logaru::Formatter.new { |message| "#{message}\n" }
+
+# => Logaru::InvalidPatternError: pattern must accept 4 arguments
+```
+
+### Thread safety
+
+A logger can be shared between threads: writes are serialized, so entries are never interleaved and the log file is opened only once, even when several threads start together. Patterns run outside that lock, so they should not depend on mutable shared state — see [Concurrency](docs/ARCHITECTURE.md#concurrency).
+
+### Errors
+
+Every error raised by Logaru inherits from `Logaru::Error`:
+
+* `Logaru::InvalidFormatterError` — the formatter does not respond to `#format`.
+* `Logaru::InvalidLevelError` — the configured severity is not supported.
+* `Logaru::InvalidPatternError` — the formatter pattern is not callable or cannot receive the log arguments.
+* `Logaru::InvalidOutputError` — the logger output is neither a path nor an object responding to `#write`.
+
+## Development
+
+```bash
+git clone https://github.com/rpzerosixcode/logaru.git
+
+cd logaru
+
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run the linter (must be clean — CI fails on offenses):
+
+```bash
+bundle exec rubocop
+```
+
+Run both (default Rake task):
+
+```bash
+bundle exec rake
+```
+
+Sanity-check the gem build (also run in CI):
+
+```bash
+gem build logaru.gemspec --strict
+```
+
+## Releasing
+
+Release by pushing a tag that matches `Logaru::VERSION` (see `lib/logaru/version.rb`):
+
+```bash
+git tag v0.1.0
+
+git push origin v0.1.0
+```
+
+`.github/workflows/release.yml` then runs the same checks as CI (RSpec, RuboCop and a strict gem build on Ruby 3.3, 3.4 and 4.0), checks the tag against `Logaru::VERSION`, publishes the gem to RubyGems and opens a GitHub release with the gem attached. Publishing uses RubyGems trusted publishing (OIDC), so no API token is stored in the repository — configure a trusted publisher for `logaru` on RubyGems.org (workflow file `.github/workflows/release.yml`) before the first tag.
+
+## Documentation
+
+* [Architecture](docs/ARCHITECTURE.md) — components, entry lifecycle, output resolution and concurrency model.
+* [Features](docs/FEATURES.md) — what the library does today and what is still missing.
+* [Security](docs/SECURITY.md) — threat surface, known limitations and how to report a vulnerability.
+
+The repository layout, the CI matrix and the Dependabot setup are documented in [Architecture](docs/ARCHITECTURE.md#repository-layout).
+
+## Requirements
+
+* Ruby >= 3.3.0 (see `logaru.gemspec`).
+
+## License
+
+Logaru is available under the MIT License — see [LICENSE](LICENSE).
+
+## Links
+
+* Homepage: https://github.com/rpzerosixcode/logaru
+* Changelog: https://github.com/rpzerosixcode/logaru/blob/main/CHANGELOG.md

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new(:rubocop)
+
+desc "Run spec and rubocop"
+task default: %i[spec rubocop]

data/docs/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Architecture
+
+How Logaru is built internally. Installation and usage live in the [README](../README.md); the capability checklist is in [FEATURES.md](FEATURES.md).
+
+## Design goals
+
+* **Formatting without global state:** each logger owns its formatter, so changing the output of one logger never changes another.
+* **Fail fast:** level, formatter, pattern and output are validated in `Logger.new` instead of failing on the first write.
+* **Cheap writes:** entries below the configured level are discarded before formatting, and the log file is opened once and reused.
+* **Safe sharing:** one logger can be used by several threads without interleaved or lost entries.
+* **No runtime dependencies:** standard library only (`fileutils`, `pathname`).
+
+## Components
+
+| Component | File | Responsibility |
+| --- | --- | --- |
+| `Logaru` | `lib/logaru.rb` | Loads the components and exposes `Logaru.root`. |
+| `Logaru::VERSION` | `lib/logaru/version.rb` | Gem version. |
+| `Logaru::Level` | `lib/logaru/level.rb` | Numeric severities (`DEBUG`…`UNKNOWN`), `coerce` (constant, name or symbol) and `name_for`. |
+| `Logaru::Formatter` | `lib/logaru/formatter.rb` | Owns the pattern, validates its arity and turns an entry into text (`#format`). |
+| `Logaru::Logger` | `lib/logaru/logger.rb` | Filters by level, resolves the output, manages the log file and serializes writes with a mutex. |
+| `Logaru::Error` | `lib/logaru/errors.rb` | Error hierarchy: `InvalidFormatterError`, `InvalidLevelError`, `InvalidPatternError`, `InvalidOutputError`. |
+
+## Entry lifecycle
+
+```text
+logger.info("message", progname: "web")
+  -> severity = Level.coerce(INFO)
+  -> return if severity < @level                                 # no formatting, no write, no file created
+  -> @formatter.format(severity, Time.now, progname, message)     # outside the lock
+  -> @mutex.synchronize { resolved_device.write(text) }
+```
+
+## Output resolution
+
+| `file:` value | Device used | Owner |
+| --- | --- | --- |
+| omitted or `nil` | `$stdout`, resolved on every write | process |
+| `String`, `Pathname`, or an object with `to_path` and without `write` | file opened in append mode | the logger (`#close` releases it) |
+| object responding to `#write` (`File`, `StringIO`, `Tempfile`, custom device) | the object itself | the caller, never closed by Logaru |
+
+`Pathname` is classified explicitly: it responds to `#write`, but that call replaces the whole file, so treating it as a stream would overwrite the log on every entry. Path-like values are therefore detected before the `#write` check, and `#output` always returns the value given to `file:`.
+
+## Log file lifecycle
+
+1. Opened on the first write that passes the level, so a logger that logs nothing creates neither the file nor its directories.
+2. Parent directories are created with `FileUtils.mkdir_p`.
+3. Opened in append mode with `sync` (default `true`), so every entry is flushed on write.
+4. The handle is reused between writes and exposed by `#device`.
+5. `#close` releases only the file the logger opened, and the next write reopens the path in append mode — the supported path for external rotation (close, rename, keep logging).
+
+## Concurrency
+
+* A single `Mutex` per logger serializes device resolution, writing and `#close`, so entries never interleave, none is lost and the file is opened exactly once even when threads start together.
+* Formatting runs outside the lock (it is the expensive step), so patterns must not depend on mutable shared state — keep them pure.
+* Locking is per logger and per process: Logaru does not use `flock`, so independent processes writing to the same file are not synchronized.
+
+## Repository layout
+
+```text
+lib/
+  logaru.rb            # entry point — Logaru namespace
+  logaru/version.rb    # Logaru::VERSION
+  logaru/errors.rb     # Logaru::Error and the specific errors
+  logaru/level.rb      # Logaru::Level severities
+  logaru/formatter.rb  # Logaru::Formatter — patterns and arity validation
+  logaru/logger.rb     # Logaru::Logger — levels, output and file management
+
+spec/
+  spec_helper.rb       # RSpec configuration (loads spec/support)
+  unit/                # Unit tests
+  integration/         # Integration tests
+  e2e/                 # End-to-end tests (placeholder)
+  support/             # Helpers / shared examples
+
+docs/                   # User documentation (README + this file, FEATURES, SECURITY)
+
+.github/workflows/      # ci.yml — RSpec + RuboCop + gem build
+.github/dependabot.yml  # weekly dependency updates
+
+Rakefile                # default task: spec + rubocop
+logaru.gemspec          # Gem metadata and dependencies
+Gemfile                 # source + gemspec
+.rubocop.yml            # Style rules
+.rspec                  # --require spec_helper
+```
+
+## Automated checks
+
+CI (`.github/workflows/ci.yml`) runs on every push and pull request to `main` and `develop`:
+
+* RSpec suite and `bundle exec rubocop --parallel` on `ubuntu-latest` with Ruby `3.3`, `3.4` and `4.0` (fail-fast disabled);
+* `gem build logaru.gemspec --strict` as a packaging sanity check;
+* Dependabot opens weekly pull requests for Bundler and GitHub Actions dependencies.
+
+Locally, `bundle exec rake` runs the same checks available in the development environment.
+
+## Release pipeline
+
+`.github/workflows/release.yml` runs when a `v*` tag is pushed (the tagging steps are in the [README](../README.md#releasing)):
+
+1. **Validate** — the same matrix and checks as CI: RSpec, `bundle exec rubocop --parallel` and `gem build logaru.gemspec --strict` on `ubuntu-latest` with Ruby `3.3`, `3.4` and `4.0` (fail-fast disabled).
+2. **Publish** — fails unless the tag equals `Logaru::VERSION`, rebuilds the gem, authenticates to RubyGems over OIDC (trusted publishing), pushes the gem and creates the GitHub release with the gem attached.
+
+The validate job is a mirror of the CI test job, so a tag can never publish code that CI would reject. Publishing runs `gem build logaru.gemspec --strict`, which writes `logaru-<version>.gem` in the workspace; locally, `bundle exec rake build` (from `bundler/gem_tasks`, required by the `Rakefile`) writes `pkg/logaru-<version>.gem`. `pkg/` and `*.gem` are git-ignored. The release job declares `id-token: write` for OIDC and `contents: write` to create the release.
+
+`Logaru::VERSION` (`lib/logaru/version.rb`) is the single source of truth: the gemspec reads it, the workflow compares it with the tag and `Gemfile.lock` records it. A release therefore means bumping that file, moving the `Unreleased` entries into a dated section in `CHANGELOG.md` and pushing the `v<version>` tag.

data/docs/FEATURES.md

@@ -0,0 +1,38 @@
+# Features
+
+What Logaru offers in `1.0.0`. Usage examples are in the [README](../README.md); internal design in [ARCHITECTURE.md](ARCHITECTURE.md).
+
+## Severities and filtering
+
+* Six severities: `debug`, `info`, `warn`, `error`, `fatal` and `unknown`, plus the generic `log(severity, message, progname:)`.
+* A level can be given as a `Logaru::Level` constant, a name or a symbol, in any case.
+* Entries below the configured level are discarded before formatting: they cost nothing and never create a log file. The default level is `debug`.
+
+## Output
+
+* Standard output by default (`$stdout`, resolved on every write).
+* Log files through a `String` or a `Pathname`: created on first use, parent directories created automatically, append mode, handle reused, one flush per entry.
+* Any object responding to `#write` (`File`, `StringIO`, `Tempfile`, custom devices) — streams Logaru did not open are never closed by it.
+* `sync: false` for buffered writes, `#close` to release the file, `#device` and `#output` for introspection.
+
+## Formatting
+
+* Default pattern (`[<timestamp>] [<progname> ]<LEVEL>: <message>`) or a custom `pattern:`/block for each logger.
+* A `Logaru::Formatter` instance can be built once and injected into several loggers.
+* Patterns are validated when created: they must be callable and able to receive the four entry arguments (severity, datetime, progname, message). Lambdas, variadic blocks, optional parameters and callables without `#parameters` are supported.
+* Optional `progname` per entry.
+
+## Concurrency
+
+* A logger can be shared between threads: entries are written atomically and the log file is opened exactly once.
+* `#close` is safe while other threads are logging.
+
+## Operations
+
+* External rotation (rename or replace the file) works through `#close` and the automatic reopen on the next write.
+* Invalid configuration (formatter, level, pattern, output) raises a `Logaru::Error` subclass at `Logger.new`.
+* No runtime dependencies; Ruby >= 3.3.
+
+## Not available yet
+
+Log rotation by size or date, asynchronous logging, ANSI colors, message sanitization (see [SECURITY.md](SECURITY.md)) and cross-process locking are not implemented. They are candidates for future minor versions and do not affect the `1.0` API, which follows Semantic Versioning.

data/docs/SECURITY.md

@@ -0,0 +1,38 @@
+# Security
+
+How Logaru handles untrusted input, and what it does not protect against.
+
+Supported versions: the latest `1.x` release. `1.0.0` is the first stable version; fixes are prepared on `develop`, merged into `main` and published as a new patch or minor release from a tag matching `Logaru::VERSION`.
+
+## Threat surface
+
+* No runtime dependencies — only the Ruby standard library (`fileutils`, `pathname`).
+* No `eval`, no dynamic dispatch of user input, no deserialization and no execution of external content.
+* No network access and no telemetry: the library neither collects nor transmits data.
+* Inputs are the logger options (`level`, `file`, `formatter`, `pattern`, `sync`), the messages and the progname; they affect only local formatting and writing.
+* Paths are used as given: `file:` is opened in append mode and missing parent directories are created. Logaru does not restrict or sandbox paths, so never build a log path from untrusted input.
+
+## Considerations
+
+### Control characters in messages (not mitigated)
+
+Messages are written exactly as received, so control characters (`\e`, `\r`, `\n`, `\b`) can forge log lines or manipulate the terminal of whoever reads the log — for example `"ok\rINFO: all good"`. Neither `Logaru::Formatter` nor `Logaru::Logger` sanitizes messages: sanitize at the source, or return an escaped message from a custom pattern.
+
+### Sensitive content
+
+Messages may contain personal data, credentials in URLs, tokens or payloads. The library does not mask, redact or filter anything: retention policy, masking and access control are the application's responsibility.
+
+### File permissions and lifetime
+
+The file is created with the process defaults (`umask`/ACLs apply) in append mode, and missing parent directories are created with default permissions. The handle stays open until `Logger#close`, so release it before archiving or removing the file — on Windows an open file cannot be renamed or deleted.
+
+### Writing from several processes
+
+Synchronization is per logger and per process. Two processes appending to the same file are not coordinated, so entries may interleave when writes are buffered: keep the default `sync: true`, use one writer per file, or send logs to an external collector.
+
+## Reporting a vulnerability
+
+* Report privately through GitHub: **Security → Advisories → Report a vulnerability** (<https://github.com/rpzerosixcode/logaru/security/advisories/new>).
+* Do not open a public issue for something exploitable.
+* Include the version or commit, Ruby version, operating system, reproduction steps, impact and, when possible, a suggested fix.
+* There is no bug bounty program. Gem releases require MFA (`rubygems_mfa_required`) and fixes are noted in the changelog.

data/lib/logaru/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Logaru
+    # Base class for errors raised by Logaru.
+    class Error < StandardError; end
+
+    # Raised when a logger is configured with an invalid formatter.
+    class InvalidFormatterError < Error; end
+
+    # Raised when a logger receives an unsupported severity.
+    class InvalidLevelError < Error; end
+
+    # Raised when a formatter is configured with an unusable pattern.
+    class InvalidPatternError < Error; end
+
+    # Raised when a logger receives an output that cannot be written to.
+    class InvalidOutputError < Error; end
+end

data/lib/logaru/formatter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+require_relative "level"
+
+module Logaru
+    # Formats log entries using a configurable pattern.
+    class Formatter
+        # Number of arguments every pattern must be able to receive.
+        PATTERN_ARITY = 4
+
+        # Pattern used when the formatter is instantiated without one.
+        DEFAULT_PATTERN = proc do |severity, datetime, progname, message|
+            prefix = progname ? "#{progname} " : ""
+            "[#{datetime}] #{prefix}#{Level.name_for(severity).upcase}: #{message}\n"
+        end
+
+        attr_reader :pattern
+
+        # Initializes the formatter with an optional pattern. A block takes
+        # precedence over the +pattern+ option, so both
+        # Formatter.new(pattern: proc { ... }) and Formatter.new { ... } work.
+        def initialize(pattern: DEFAULT_PATTERN, &block)
+            @pattern = block || pattern
+            validate_pattern!
+        end
+
+        # Formats a log entry using the configured pattern.
+        def format(severity, datetime, progname, message)
+            @pattern.call(severity, datetime, progname, message)
+        end
+
+        private
+
+        def validate_pattern!
+            raise InvalidPatternError, "pattern must respond to #call" unless @pattern.respond_to?(:call)
+            return if compatible_arity?
+
+            raise InvalidPatternError, "pattern must accept #{PATTERN_ARITY} arguments"
+        end
+
+        # Returns true when the pattern can be called with the log arguments.
+        def compatible_arity?
+            return true unless @pattern.respond_to?(:parameters)
+
+            parameters = @pattern.parameters
+            required = parameters.count { |type, _name| type == :req }
+            optional = parameters.count { |type, _name| type == :opt }
+            variadic = parameters.any? { |type, _name| type == :rest }
+
+            required <= PATTERN_ARITY && (variadic || required + optional >= PATTERN_ARITY)
+        end
+    end
+end

data/lib/logaru/level.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Logaru
+    # Numeric values for the supported log severities.
+    class Level
+        DEBUG   = 0
+        INFO    = 1
+        WARN    = 2
+        ERROR   = 3
+        FATAL   = 4
+        UNKNOWN = 5
+
+        # Maps level names to their numeric values.
+        LEVELS = {
+            "debug" => DEBUG,
+            "info" => INFO,
+            "warn" => WARN,
+            "error" => ERROR,
+            "fatal" => FATAL,
+            "unknown" => UNKNOWN,
+        }.freeze
+
+        class << self
+            # Converts a numeric or textual level to its numeric value.
+            def coerce(value)
+                return value if value.is_a?(Integer) && LEVELS.value?(value)
+
+                name = value.to_s.downcase
+                return LEVELS.fetch(name) if LEVELS.key?(name)
+
+                raise InvalidLevelError, "unsupported log level: #{value.inspect}"
+            end
+
+            # Returns the canonical name for a numeric or textual level.
+            def name_for(value)
+                LEVELS.key(coerce(value))
+            end
+        end
+    end
+end

data/lib/logaru/logger.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "pathname"
+
+require_relative "errors"
+require_relative "level"
+require_relative "formatter"
+
+module Logaru
+    # Writes log entries through a formatter to the console or a file.
+    class Logger
+        attr_reader :formatter, :level, :output
+
+        # Initializes the logger with a level and optional output and formatting.
+        #
+        # +file+ accepts a path (String or Pathname) or any object responding to
+        # #write, such as an open File or a StringIO. When it is omitted, entries
+        # are written to $stdout. +sync+ controls whether every write is flushed,
+        # which defaults to true so that log files are always up to date.
+        #
+        # Formatting is handled by a Logaru::Formatter built here. Pass +pattern+
+        # (or a block) to configure it, or +formatter+ to inject an instance —
+        # never both.
+        #
+        # Entries are written while holding a mutex, so the same logger can be
+        # shared between threads. The formatter pattern is called outside the
+        # lock, so it must not depend on mutable shared state.
+        def initialize(formatter: nil, level: Level::DEBUG, file: nil, sync: true, pattern: nil, &block)
+            validate_formatter_options!(formatter, pattern, block)
+            @level = Level.coerce(level)
+            @output = file
+            @sync = sync
+            @formatter = formatter || build_formatter(pattern, &block)
+            @resolved_device = nil
+            @owned = false
+            @mutex = Mutex.new
+            validate_formatter!
+            validate_output!
+        end
+
+        # Logs a message using the configured formatter.
+        def log(severity, message, progname: nil)
+            severity = Level.coerce(severity)
+            return if severity < @level
+
+            formatted = @formatter.format(severity, Time.now, progname, message)
+            write(formatted)
+        end
+
+        # Logs a debug message.
+        def debug(message, progname: nil)
+            log(Level::DEBUG, message, progname:)
+        end
+
+        # Logs an informational message.
+        def info(message, progname: nil)
+            log(Level::INFO, message, progname:)
+        end
+
+        # Logs a warning message.
+        def warn(message, progname: nil)
+            log(Level::WARN, message, progname:)
+        end
+
+        # Logs an error message.
+        def error(message, progname: nil)
+            log(Level::ERROR, message, progname:)
+        end
+
+        # Logs a fatal error message.
+        def fatal(message, progname: nil)
+            log(Level::FATAL, message, progname:)
+        end
+
+        # Logs a message with an unknown severity.
+        def unknown(message, progname: nil)
+            log(Level::UNKNOWN, message, progname:)
+        end
+
+        # Returns the IO used for writing, opening the log file on first use.
+        def device
+            @mutex.synchronize { resolved_device }
+        end
+
+        # Closes the log file opened by the logger. The file is reopened on the
+        # next write, which keeps external log rotation working. Streams and
+        # objects provided through +file+ are left untouched.
+        #
+        # Safe to call from another thread: it waits for the write in progress
+        # before releasing the handle.
+        def close
+            @mutex.synchronize do
+                @resolved_device.close if @owned && @resolved_device.respond_to?(:close)
+                @resolved_device = nil
+                @owned = false
+            end
+        end
+
+        private
+
+        # Rejects a formatter injected together with a pattern or a block.
+        def validate_formatter_options!(formatter, pattern, block)
+            return unless formatter && (pattern || block)
+
+            raise InvalidFormatterError, "pass either formatter or pattern, not both"
+        end
+
+        # Builds the formatter used when none is injected, honoring a pattern.
+        def build_formatter(pattern, &)
+            Formatter.new(pattern: pattern || Formatter::DEFAULT_PATTERN, &)
+        end
+
+        def validate_formatter!
+            return if @formatter.respond_to?(:format)
+
+            raise InvalidFormatterError, "formatter must respond to #format (use Logaru::Formatter.new)"
+        end
+
+        def validate_output!
+            return if @output.nil? || path_like?(@output) || @output.respond_to?(:write)
+
+            raise InvalidOutputError, "output must be a path or an object responding to #write"
+        end
+
+        def write(message)
+            @mutex.synchronize { resolved_device.write(message) }
+        end
+
+        # Returns the target of the log entries, opening the log file on first
+        # use and reusing it on the following writes. Callers must hold the mutex
+        # so the file is opened (and the parent directories created) only once.
+        def resolved_device
+            return $stdout if @output.nil?
+
+            @resolved_device ||= open_device
+        end
+
+        # Returns true when the value stands for a file path instead of a stream.
+        #
+        # Pathname is handled explicitly because it responds to #write, and that
+        # method writes the whole file in one call: treating a Pathname as a
+        # stream would make every entry overwrite the log file.
+        def path_like?(value)
+            value.is_a?(String) || value.is_a?(Pathname) || (!value.respond_to?(:write) && value.respond_to?(:to_path))
+        end
+
+        # Opens the log file for path targets and returns caller-owned streams as
+        # they are.
+        def open_device
+            return @output unless path_like?(@output)
+
+            @owned = true
+            open_file(@output)
+        end
+
+        # Opens (creating, when needed, the parent directories) the log file in
+        # append mode. The handle is kept open and released by #close, so entries
+        # are appended to the same file between writes.
+        def open_file(path)
+            path = path.to_path if path.respond_to?(:to_path)
+            FileUtils.mkdir_p(File.dirname(path))
+            # The handle is intentionally kept open until #close, so the block
+            # form of File.open would defeat the reuse between writes.
+            file = File.open(path, "a") # rubocop:disable Style/FileOpen
+            file.sync = @sync
+            file
+        end
+    end
+end

data/lib/logaru/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Logaru
+    VERSION = "1.0.0"
+end

data/lib/logaru.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "logaru/version"
+require_relative "logaru/errors"
+require_relative "logaru/level"
+require_relative "logaru/formatter"
+require_relative "logaru/logger"
+
+# Entry point of the Logaru library.
+module Logaru
+    class << self
+        # Returns the absolute path to the gem root directory.
+        def root
+            File.expand_path("..", __dir__)
+        end
+    end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: logaru
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- rpzerosixcode
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.4'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.90'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.90'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: Ruby library focused on clear, organized, and configurable log output
+  for applications.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- docs/ARCHITECTURE.md
+- docs/FEATURES.md
+- docs/SECURITY.md
+- lib/logaru.rb
+- lib/logaru/errors.rb
+- lib/logaru/formatter.rb
+- lib/logaru/level.rb
+- lib/logaru/logger.rb
+- lib/logaru/version.rb
+homepage: https://github.com/rpzerosixcode/logaru
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/rpzerosixcode/logaru
+  source_code_uri: https://github.com/rpzerosixcode/logaru/tree/main
+  documentation_uri: https://github.com/rpzerosixcode/logaru#readme
+  changelog_uri: https://github.com/rpzerosixcode/logaru/blob/main/CHANGELOG.md
+  keywords: ruby, logger, logging, logs
+  rubygems_mfa_required: 'true'
+post_install_message:
+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.5.22
+signing_key:
+specification_version: 4
+summary: A Ruby library for clear, organized, and configurable log output.
+test_files: []