public interface IAppLogger
  {
      /// <summary>
      /// Log a debug/detail message intended for developers or verbose diagnostics.
      /// </summary>
      /// <param name="message">The message to log.</param>
      void Debug(object? message);

      /// <summary>
      /// Log an informational message that represents normal operation or key milestones.
      /// </summary>
      /// <param name="message">The message to log.</param>
      void Info(object? message);

      /// <summary>
      /// Log a warning about an unexpected but recoverable condition.
      /// </summary>
      /// <param name="message">The warning message to log.</param>
      void Warn(object? message);

      /// <summary>
      /// Log an error. Implementations may include exception details when <paramref name="ex"/> is provided.
      /// </summary>
      /// <param name="message">The error message to log.</param>
      /// <param name="ex">Optional exception associated with the error.</param>
      void Error(object? message, Exception? ex = null);
  }

    public sealed class NullLogger : IAppLogger
    {
        /// <summary>
        /// Shared instance to avoid unnecessary allocations.
        /// </summary>
        public static readonly NullLogger Instance = new NullLogger();

        // Private ctor encourages use of Instance when appropriate.
        internal NullLogger() { }

        public void Debug(object? message) { /* intentionally no-op */ }
        public void Info(object? message) { /* intentionally no-op */ }
        public void Warn(object? message) { /* intentionally no-op */ }
        public void Error(object? message, Exception? ex = null) { /* intentionally no-op */ }
    }
}
using log4net;
using log4net.Appender;
using log4net.Layout;
using System;
using System.Collections.Generic;
using System.IO;
using System.Reflection;

namespace MyProject.Lib.Logging
{
    /// <summary>
    /// Static entry point for library diagnostics.
    /// </summary>
    /// <remarks>
    /// <para>
    /// Purpose
    /// - Provide a small, test-friendly logging façade for the library so internal components can
    ///   emit diagnostics without depending on a concrete logging framework.
    /// - Expose a single adjustable global logger via <see cref="Current"/> and convenient forwarding
    ///   helpers (<see cref="Debug(string)"/>, <see cref="Info(string)"/>, <see cref="Warn(string)"/>,
    ///   <see cref="Error(string, Exception?)"/>) so call sites remain concise and testable.
    /// </para>
    ///
    /// <para>
    /// Default behavior and test guidance
    /// - By default <see cref="Current"/> is a <see cref="NullLogger"/> which drops messages. Tests
    ///   and hosts should replace <see cref="Current"/> with a deterministic implementation
    ///   (for example a <c>TestLogger</c>) rather than enabling file-based logging when possible.
    /// - Use <see cref="Disable"/> to restore no-op behavior in teardown. This prevents tests from
    ///   producing flaky file/IO side-effects.
    /// </para>
    ///
    /// <para>
    /// File-based logging via log4net
    /// - Use <see cref="SetFile(string,string)"/> to programmatically enable a rolling file appender:
    ///     - The method resolves and normalizes the path, ensures the directory exists and performs a
    ///       lightweight write probe to fail early on permission/path issues.
    ///     - If the probe succeeds the method registers a UTF-8 rolling appender and sets
    ///       <see cref="Current"/> to a <see cref="Log4NetAdapter"/> bound to the configured repository.
    /// - Hosts may instead call <see cref="Enable"/> to adopt the host's existing log4net configuration.
    /// - Note: programmatic configuration performed by this class mutates the global log4net repository.
    ///   Only call these helpers during process startup or in controlled integration tests.
    /// </para>
    ///
    /// <para>
    /// Non-throwing & best-effort contract
    /// - Logging is best-effort. Implementations of <see cref="IAppLogger"/> must not throw from log calls.
    /// - <see cref="SetFile"/> performs defensive checks and will throw on invalid arguments or unwritable
    ///   paths so hosts can surface configuration errors early. Consumers should catch these exceptions
    ///   during host initialization; unit tests should avoid using this method.
    /// </para>
    ///
    /// <para>
    /// Concurrency and lifetime
    /// - The <see cref="Current"/> reference is assigned atomically but there is no internal locking for
    ///   concurrent set/get. Set the global logger early on a single thread during startup to avoid
    ///   races. For per-component scoping prefer constructor injection of an <see cref="IAppLogger"/>.
    /// - The logging façade and its adapters must be safe for concurrent use; the library may call into
    ///   the logger from parallel tasks or test runners.
    /// </para>
    ///
    /// <para>
    /// Diagnostic tokens and verbosity
    /// - The library uses compact, stable tokens in messages to enable reliable assertions in tests.
    /// - The file appender uses a human-friendly layout including timestamp, level, logger and message;
    ///   callers can adjust verbosity via the <paramref name="logLevel"/> parameter to <see cref="SetFile"/>.
    /// </para>
    ///
    /// <para>
    /// Recommendations for hosts and CI
    /// - Prefer wiring a host-level logger and calling <see cref="Enable"/> or setting <see cref="Current"/>
    ///   to an adapter that forwards to the host. This avoids the library performing global repository changes.
    /// - Use file-based logging sparingly in CI; prefer capturing test logs via injected test loggers to keep
    ///   pipelines hermetic and fast.
    /// </para>
    ///
    /// <para>
    /// Example
    /// <code>
    /// // Programmatic file logging (call during startup)
    /// Log.SetFile("C:\\logs\\convert.log", "DEBUG");
    ///
    /// // Or use a test logger in unit tests
    /// Log.Current = new TestLogger();
    /// </code>
    /// </para>
    /// </remarks>
    public static class Log
    {
        private static IAppLogger _current = new NullLogger();

        /// <summary>
        /// Gets or sets the active logger. If set to null, a no-op logger is used.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Consumers (tests, hosts) may set this property to supply a custom logger (for example a
        /// test logger). Assigning null will restore a <see cref="NullLogger"/> instance to preserve
        /// no-op behavior.
        /// </para>
        /// <para>
        /// Assignments are atomic for the reference; however concurrent read/write races are not
        /// synchronized. Set the global logger early during initialization to avoid race conditions.
        /// </para>
        /// </remarks>
        public static IAppLogger Current
        {
            get => _current;
            set => _current = value ?? new NullLogger();
        }

        /// <summary>
        /// Configure file-based logging using a programmatically-created log4net rolling appender.
        /// </summary>
        /// <param name="logFilePath">Target log file path. The method will create containing directories as needed.</param>
        /// <param name="logLevel">Optional log level name (All/Debug/Info/Warn/Error/Fatal/Off). Defaults to "All".</param>
        /// <remarks>
        /// <para>
        /// This helper performs the following defensive steps before enabling file logging:
        /// - Resolves and normalizes the supplied path.
        /// - Ensures the target directory exists.
        /// - Probes write access by opening the file for append and immediately closing it.
        /// - Creates a rolling file appender with a UTF-8 pattern layout and configures the log4net
        ///   repository for the current entry assembly.
        /// </para>
        /// <para>
        /// The method throws an <see cref="ArgumentException"/> for invalid arguments and an
        /// <see cref="IOException"/> when the path is not writable. Callers should catch and handle
        /// these exceptions during host startup; tests should avoid calling this method and instead
        /// set <see cref="Current"/> directly to a deterministic test logger.
        /// </para>
        /// </remarks>
        public static void SetFile(string logFilePath, string logLevel = "All")
        {
            if (string.IsNullOrWhiteSpace(logFilePath))
                throw new ArgumentException("logFilePath cannot be null or empty.", nameof(logFilePath));

            var fullPath = ResolvePath(logFilePath);
            EnsureDirectoryExists(fullPath);
            ProbeWriteAccess(fullPath);

            var appender = CreateRollingAppender(fullPath);
            var level = ParseLogLevel(logLevel);

            ConfigureRepository(appender, level);
            Current = new Log4NetAdapter(LogManager.GetLogger(typeof(Log)));
        }

        /// <summary>
        /// Convert the supplied path into an absolute, normalized form.
        /// </summary>
        /// <param name="logFilePath">Original path provided by the caller (may be relative).</param>
        /// <returns>Absolute normalized file path.</returns>
        /// <remarks>
        /// Uses <see cref="Path.GetFullPath(string)"/> to resolve relative paths against the current
        /// working directory. No IO is performed by this helper.
        /// </remarks>
        private static string ResolvePath(string logFilePath)
        {
            return Path.GetFullPath(logFilePath);
        }

        /// <summary>
        /// Ensure the directory for the given file path exists, creating it if necessary.
        /// </summary>
        /// <param name="fullPath">Absolute file path whose directory should be present.</param>
        /// <remarks>
        /// - Extracts the directory portion of <paramref name="fullPath"/> and creates it when missing.
        /// - Any IO exceptions (for example insufficient permissions) will bubble to the caller.
        /// </remarks>
        private static void EnsureDirectoryExists(string fullPath)
        {
            var directory = Path.GetDirectoryName(fullPath);
            if (!string.IsNullOrEmpty(directory) && !Directory.Exists(directory))
            {
                Directory.CreateDirectory(directory);
            }
        }

        /// <summary>
        /// Probe whether the process can open the target file for appending.
        /// </summary>
        /// <param name="fullPath">Absolute path to the candidate log file.</param>
        /// <remarks>
        /// This method attempts to open the file with <see cref="FileMode.Append"/> and immediately
        /// closes it. If the file cannot be opened for write access (permission denied, path locked,
        /// invalid path) the method wraps and throws <see cref="IOException"/> with a helpful message.
        /// Use this probe to fail early during host startup rather than letting log4net fail silently
        /// or produce confusing errors later.
        /// </remarks>
        private static void ProbeWriteAccess(string fullPath)
        {
            try
            {
                using (var fs = new FileStream(fullPath, FileMode.Append, FileAccess.Write, FileShare.Read))
                {
                    // just testing write access
                }
            }
            catch (Exception ex)
            {
                throw new IOException($"Cannot write to log file path '{fullPath}'. Check permissions and that the path is valid.", ex);
            }
        }

        /// <summary>
        /// Create a configured <see cref="RollingFileAppender"/> that writes UTF-8 encoded logs.
        /// </summary>
        /// <param name="fullPath">Absolute path to the target log file.</param>
        /// <returns>Initialized <see cref="RollingFileAppender"/> suitable for registration with log4net.</returns>
        /// <remarks>
        /// The returned appender:
        /// - Uses a human-friendly pattern layout that includes timestamps, level, logger and message.
        /// - Rolls files by size with a moderate retention policy (5 backups, 10MB each).
        /// - Uses a minimal locking model to reduce contention while allowing other readers to tail the file.
        /// - Is activated (options applied) before being returned.
        /// </remarks>
        private static RollingFileAppender CreateRollingAppender(string fullPath)
        {
            var layout = new PatternLayout
            {
                ConversionPattern = "%date %-5level %logger - %message%newline%exception"
            };
            layout.ActivateOptions();

            var roller = new RollingFileAppender
            {
                AppendToFile = true,
                File = fullPath,
                Layout = layout,
                MaxSizeRollBackups = 5,
                MaximumFileSize = "10MB",
                RollingStyle = RollingFileAppender.RollingMode.Size,
                StaticLogFileName = true,
                LockingModel = new FileAppender.MinimalLock(),
                Encoding = System.Text.Encoding.UTF8
            };
            roller.ActivateOptions();

            return roller;
        }

        /// <summary>
        /// Parse a textual log level token into a log4net <see cref="log4net.Core.Level"/>.
        /// </summary>
        /// <param name="logLevel">Log level string provided by the user (case-insensitive).</param>
        /// <returns>Corresponding log4net level; falls back to <c>All</c> when unknown.</returns>
        /// <remarks>
        /// - Recognized tokens: ALL, DEBUG, INFO, WARN, ERROR, FATAL, OFF (case-insensitive).
        /// - The method resolves the log4net repository for the current entry assembly and reads the level
        ///   from the repository's level map. This allows the returned value to be consistent with the
        ///   repository's configured levels.
        /// - When the repository or level cannot be resolved the method falls back to <c>Level.All</c>.
        /// </remarks>
        private static log4net.Core.Level ParseLogLevel(string logLevel)
        {
            var levelMap = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
            {
                ["ALL"] = "ALL",
                ["DEBUG"] = "DEBUG",
                ["INFO"] = "INFO",
                ["WARN"] = "WARN",
                ["ERROR"] = "ERROR",
                ["FATAL"] = "FATAL",
                ["OFF"] = "OFF"
            };

            var normalizedLevel = (logLevel ?? "ALL").Trim().ToUpperInvariant();
            var levelName = levelMap.ContainsKey(normalizedLevel) ? levelMap[normalizedLevel] : "ALL";

            var entry = Assembly.GetEntryAssembly();
            var repoAssembly = (Assembly)(entry ?? Assembly.GetExecutingAssembly());
            var repo = LogManager.GetRepository(repoAssembly);
            var hierarchy = repo as log4net.Repository.Hierarchy.Hierarchy;

            var level = hierarchy?.LevelMap[levelName] ?? hierarchy?.LevelMap["ALL"] ?? log4net.Core.Level.All;
            return level;
        }

        /// <summary>
        /// Configure the log4net repository with the provided appender and root level.
        /// </summary>
        /// <param name="appender">Appender to register with the repository.</param>
        /// <param name="level">Root logging level to apply to the repository.</param>
        /// <remarks>
        /// <para>
        /// This method:
        /// - Resolves the log4net repository for the entry assembly (or current assembly fallback).
        /// - Resets existing configuration to ensure deterministic behaviour for programmatic setup.
        /// - Registers the provided appender using <see cref="log4net.Config.BasicConfigurator.Configure"/>.
        /// - Sets the root logger level and marks the hierarchy as configured.
        /// </para>
        /// <para>
        /// Note: this routine intentionally performs global repository changes. Callers should only
        /// invoke it during host initialization or in dedicated integration tests. It is not suitable
        /// for ad-hoc changes inside library helpers that expect to be reentrant.
        /// </para>
        /// </remarks>
        private static void ConfigureRepository(RollingFileAppender appender, log4net.Core.Level level)
        {
            var entry = Assembly.GetEntryAssembly();
            var repoAssembly = (Assembly)(entry ?? Assembly.GetExecutingAssembly());
            var repo = LogManager.GetRepository(repoAssembly);

            var hierarchy = repo as log4net.Repository.Hierarchy.Hierarchy;
            if (hierarchy != null)
            {
                hierarchy.ResetConfiguration();
            }

            log4net.Config.BasicConfigurator.Configure(repo, appender);

            if (hierarchy != null)
            {
                hierarchy.Root.Level = level;
                hierarchy.Configured = true;
            }
        }

        /// <summary>
        /// Enable logging using the existing log4net configuration.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Sets <see cref="Current"/> to a <see cref="Log4NetAdapter"/> that forwards all calls to the
        /// configured log4net repository. This is useful when the host configures log4net externally (for
        /// example via XML configuration or host wiring) and the library should piggy-back on the host's
        /// logging setup.
        /// </para>
        /// <para>
        /// For unit tests prefer setting <see cref="Current"/> directly to a test logger to keep tests
        /// deterministic and avoid file/IO side-effects.
        /// </para>
        /// </remarks>
        public static void Enable()
        {
            var logger = LogManager.GetLogger(typeof(Log));
            Current = new Log4NetAdapter(logger);
        }

        /// <summary>
        /// Disable logging and revert to a no-op logger.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Sets <see cref="Current"/> to <see cref="NullLogger"/> so subsequent library log calls are no-ops.
        /// This is useful in tests to suppress noisy logs or to temporarily disable file logging.
        /// </para>
        /// <para>
        /// This method does not modify the log4net repository configuration; appenders remain registered. To fully
        /// reset log4net one would need to interact with the repository API directly (not performed here).
        /// </para>
        /// </remarks>
        public static void Disable()
        {
            Current = new NullLogger();
        }

        /// <summary>
        /// Log a debug message via the active logger.
        /// </summary>
        /// <remarks>
        /// Forwarding method to avoid callers referencing <see cref="Current"/> directly. Implementations of
        /// <see cref="IAppLogger.Debug"/> should be non-throwing and lightweight.
        /// </remarks>
        public static void Debug(string message) => _current.Debug(message);

        /// <summary>
        /// Log an informational message via the active logger.
        /// </summary>
        /// <remarks>
        /// Intended for high-level lifecycle and milestone messages.
        /// </remarks>
        public static void Info(string message) => _current.Info(message);

        /// <summary>
        /// Log a warning via the active logger.
        /// </summary>
        /// <remarks>
        /// Warnings indicate recoverable/unexpected conditions that merit attention.
        /// </remarks>
        public static void Warn(string message) => _current.Warn(message);

        /// <summary>
        /// Log an error via the active logger, optionally with an exception.
        /// </summary>
        /// <remarks>
        /// Error logging should be used for failures that affect operation. Avoid passing large exception
        /// objects across process boundaries; prefer serializing minimal diagnostic info when logs are
        /// collected by external systems.
        /// </remarks>
        public static void Error(string message, Exception? ex = null) => _current.Error(message, ex);
    }
}