Add CompanyName property and other properties to make a reach plugin with more metadata as well as add comments for all classes and intetfaces

#9

Author: ziagham

src/FlowSynx.PluginCore/Exceptions/ErrorMessage.cs

@@ -1,17 +1,39 @@
 namespace FlowSynx.PluginCore.Exceptions;
 
+/// <summary>
+/// Represents a structured error message with a numeric code and descriptive text.
+/// </summary>
 public class ErrorMessage
 {
+    /// <summary>
+    /// The prefix used in the formatted error message, typically identifying the system (e.g., "FSX" for FlowSynX).
+    /// </summary>
     private const string PrefixErrorMessage = "FSX"; // Abbreviation for FlowSynX
 
+    /// <summary>
+    /// Gets the numeric error code associated with the error.
+    /// </summary>
     public int Code { get; }
+
+    /// <summary>
+    /// Gets the descriptive message explaining the error.
+    /// </summary>
     public string Message { get; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ErrorMessage"/> class with the specified code and message.
+    /// </summary>
+    /// <param name="code">The unique error code.</param>
+    /// <param name="message">A human-readable message describing the error.</param>
     public ErrorMessage(int code, string message)
     {
         Code = code;
         Message = message;
     }
 
+    /// <summary>
+    /// Returns a formatted string representation of the error message.
+    /// </summary>
+    /// <returns>A string in the format "[FSX{Code}] {Message}".</returns>
     public override string ToString() => $"[{PrefixErrorMessage}{Code}] {Message}";
-}
+}

src/FlowSynx.PluginCore/Exceptions/FlowSynxException.cs

@@ -1,26 +1,56 @@
 namespace FlowSynx.PluginCore.Exceptions;
 
+/// <summary>
+/// Represents errors that occur during FlowSynX operations and includes an error code and message.
+/// </summary>
 public class FlowSynxException : Exception
 {
+    /// <summary>
+    /// Gets the custom error code associated with this exception.
+    /// </summary>
     public int ErrorCode { get; }
+
+    /// <summary>
+    /// Gets the human-readable error message associated with this exception.
+    /// </summary>
     public string ErrorMessage { get; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FlowSynxException"/> class using an <see cref="ErrorMessage"/> object.
+    /// </summary>
+    /// <param name="errorMessage">The structured error message object containing the code and message.</param>
     public FlowSynxException(ErrorMessage errorMessage) : this(errorMessage.Code, errorMessage.Message)
     {
-
     }
 
-    public FlowSynxException(int errorCode, string errorMessage) : base(errorMessage)
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FlowSynxException"/> class with a specified error code and message.
+    /// </summary>
+    /// <param name="errorCode">The custom error code.</param>
+    /// <param name="errorMessage">The human-readable error message.</param>
+    public FlowSynxException(int errorCode, string errorMessage)
+        : base(errorMessage)
     {
         ErrorCode = errorCode;
         ErrorMessage = errorMessage;
     }
 
-    public FlowSynxException(int errorCode, string errorMessage, Exception innerException) : base(errorMessage, innerException)
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FlowSynxException"/> class with a specified error code, message, and inner exception.
+    /// </summary>
+    /// <param name="errorCode">The custom error code.</param>
+    /// <param name="errorMessage">The human-readable error message.</param>
+    /// <param name="innerException">The exception that is the cause of this exception.</param>
+    public FlowSynxException(int errorCode, string errorMessage, Exception innerException)
+        : base(errorMessage, innerException)
     {
         ErrorCode = errorCode;
         ErrorMessage = errorMessage;
     }
 
+    /// <summary>
+    /// Returns a formatted string representation of the exception, including the prefixed error code and message.
+    /// </summary>
+    /// <returns>A string in the format "[FSX{Code}] {Message}".</returns>
     public override string ToString() => new ErrorMessage(ErrorCode, ErrorMessage).ToString();
 }

src/FlowSynx.PluginCore/Extensions/PluginLoggerExtensions.cs

@@ -1,22 +1,45 @@
 namespace FlowSynx.PluginCore.Extensions;
 
+/// <summary>
+/// Provides extension methods for simplified logging using <see cref="IPluginLogger"/>.
+/// </summary>
 public static class PluginLoggerExtensions
 {
+    /// <summary>
+    /// Logs an informational message using the <see cref="PluginLoggerLevel.Information"/> level.
+    /// </summary>
+    /// <param name="logger">The logger to write to.</param>
+    /// <param name="message">The message to log.</param>
     public static void LogInfo(this IPluginLogger logger, string message)
     {
         logger.Log(PluginLoggerLevel.Information, message);
     }
 
+    /// <summary>
+    /// Logs an error message using the <see cref="PluginLoggerLevel.Error"/> level.
+    /// </summary>
+    /// <param name="logger">The logger to write to.</param>
+    /// <param name="message">The message to log.</param>
     public static void LogError(this IPluginLogger logger, string message)
     {
         logger.Log(PluginLoggerLevel.Error, message);
     }
 
+    /// <summary>
+    /// Logs a debug message using the <see cref="PluginLoggerLevel.Debug"/> level.
+    /// </summary>
+    /// <param name="logger">The logger to write to.</param>
+    /// <param name="message">The message to log.</param>
     public static void LogDebug(this IPluginLogger logger, string message)
     {
         logger.Log(PluginLoggerLevel.Debug, message);
     }
 
+    /// <summary>
+    /// Logs a warning message using the <see cref="PluginLoggerLevel.Warning"/> level.
+    /// </summary>
+    /// <param name="logger">The logger to write to.</param>
+    /// <param name="message">The message to log.</param>
     public static void LogWarning(this IPluginLogger logger, string message)
     {
         logger.Log(PluginLoggerLevel.Warning, message);

src/FlowSynx.PluginCore/IPlugin.cs

@@ -1,10 +1,38 @@
 namespace FlowSynx.PluginCore;
 
+/// <summary>
+/// Represents a plugin with metadata, specifications, and execution capabilities.
+/// </summary>
 public interface IPlugin
 {
+    /// <summary>
+    /// Gets the metadata describing the plugin, including its name, version, author, and other identifying information.
+    /// </summary>
     PluginMetadata Metadata { get; }
+
+    /// <summary>
+    /// Gets or sets the plugin-specific configuration or specifications used during execution.
+    /// </summary>
     PluginSpecifications? Specifications { get; set; }
+
+    /// <summary>
+    /// Gets the <see cref="Type"/> of the <see cref="Specifications"/> object.
+    /// Useful for deserialization or dynamic creation of the specification instance.
+    /// </summary>
     Type SpecificationsType { get; }
+
+    /// <summary>
+    /// Initializes the plugin with the provided logger. This method is called once before execution.
+    /// </summary>
+    /// <param name="logger">The logger to be used by the plugin for diagnostics and tracing.</param>
+    /// <returns>A task representing the asynchronous initialization operation.</returns>
     Task Initialize(IPluginLogger logger);
+
+    /// <summary>
+    /// Executes the plugin asynchronously with the provided parameters.
+    /// </summary>
+    /// <param name="parameters">The input parameters required for plugin execution.</param>
+    /// <param name="cancellationToken">A token to observe for cancellation requests.</param>
+    /// <returns>A task that represents the asynchronous operation, containing an optional result object.</returns>
     Task<object?> ExecuteAsync(PluginParameters parameters, CancellationToken cancellationToken);
-}
+}

src/FlowSynx.PluginCore/IPluginLogger.cs

@@ -1,6 +1,14 @@
 namespace FlowSynx.PluginCore;
 
+/// <summary>
+/// Defines a logging interface for plugins to emit messages with various log levels.
+/// </summary>
 public interface IPluginLogger
 {
+    /// <summary>
+    /// Logs a message with the specified severity level.
+    /// </summary>
+    /// <param name="level">The severity level of the log message (e.g., Debug, Info, Warning, Error).</param>
+    /// <param name="message">The log message to record.</param>
     void Log(PluginLoggerLevel level, string message);
 }

src/FlowSynx.PluginCore/IPluginLoggerLevel.cs

@@ -1,9 +1,28 @@
 namespace FlowSynx.PluginCore;
 
+/// <summary>
+/// Specifies the severity level of a log message emitted by a plugin.
+/// </summary>
 public enum PluginLoggerLevel
 {
+    /// <summary>
+    /// Debug-level messages used for development and diagnostic purposes.
+    /// Typically only enabled in development environments.
+    /// </summary>
     Debug = 0,
+
+    /// <summary>
+    /// Informational messages that highlight the progress or state of the plugin at a high level.
+    /// </summary>
     Information,
+
+    /// <summary>
+    /// Warning messages that indicate a potential issue or important situation that does not prevent execution.
+    /// </summary>
     Warning,
+
+    /// <summary>
+    /// Error messages that indicate a failure or problem that has impacted or halted execution.
+    /// </summary>
     Error
 }

src/FlowSynx.PluginCore/PluginMetadata.cs

@@ -1,15 +1,130 @@
-namespace FlowSynx.PluginCore;
+using System.Text.RegularExpressions;
 
+namespace FlowSynx.PluginCore;
+
+/// <summary>
+/// Represents metadata information about a plugin including its identity, version,
+/// company, descriptive details, and repository information.
+/// Constructs a fully-qualified plugin type identifier based on the company name, namespace, and plugin name.
+/// </summary>
 public class PluginMetadata
 {
-    private const string PrefixTypeName = "FlowSynx";
+    private string _companyName = default!;
+    private string _name = default!;
+
+    /// <summary>
+    /// A regular expression to validate identifiers.
+    /// Identifiers must start with a letter and contain only letters and digits.
+    /// </summary>
+    private static readonly Regex ValidIdentifierRegex = new(@"^[A-Za-z][A-Za-z0-9]*$", RegexOptions.Compiled);
 
+    /// <summary>
+    /// Gets or sets the unique identifier of the plugin.
+    /// </summary>
     public required Guid Id { get; set; }
-    public required string Name { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the plugin.
+    /// The name must start with a letter and contain only letters and digits.
+    /// </summary>
+    public required string Name
+    {
+        get => _name;
+        set => _name = ValidateIdentifier(value, nameof(Name));
+    }
+
+    /// <summary>
+    /// Gets or sets the version of the plugin.
+    /// </summary>
     public required PluginVersion Version { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the company that created the plugin.
+    /// The name must start with a letter and contain only letters and digits.
+    /// </summary>
+    public required string CompanyName
+    {
+        get => _companyName;
+        set => _companyName = ValidateIdentifier(value, nameof(CompanyName));
+    }
+
+    /// <summary>
+    /// Gets or sets an optional description of the plugin.
+    /// </summary>
     public string? Description { get; set; }
-    public string? Author { get; set; }
-    public string? Url { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of authors or maintainers of the plugin.
+    /// </summary>
+    public List<string> Authors { get; set; } = new List<string>();
+
+    /// <summary>
+    /// Gets or sets the license name under which the plugin is distributed.
+    /// </summary>
+    public string? License { get; set; }
+
+    /// <summary>
+    /// Gets or sets the URL to the license text or license information.
+    /// </summary>
+    public string? LicenseUrl { get; set; }
+
+    /// <summary>
+    /// Gets or sets the relative or absolute path/URL to the plugin icon.
+    /// </summary>
+    public string? Icon { get; set; }
+
+    /// <summary>
+    /// Gets or sets the URL to the project or documentation related to the plugin.
+    /// </summary>
+    public string? ProjectUrl { get; set; }
+
+    /// <summary>
+    /// Gets or sets the copyright notice for the plugin.
+    /// </summary>
+    public string? Copyright { get; set; }
+
+    /// <summary>
+    /// Gets or sets a simicolon-delimited list of tags used to categorize or describe the plugin.
+    /// Useful for search and filtering.
+    /// </summary>
+    public List<string> Tags { get; set; } = new List<string>();
+
+    /// <summary>
+    /// Gets or sets the URL to the source code repository of the plugin.
+    /// </summary>
+    public string? RepositoryUrl { get; set; }
+
+    /// <summary>
+    /// Gets or sets the namespace the plugin belongs to.
+    /// Used as the middle component in the plugin's type identifier.
+    /// </summary>
     public required PluginNamespace Namespace { get; set; }
-    public string Type => $"{PrefixTypeName}.{Namespace}.{Name}";
+
+    /// <summary>
+    /// Gets the full plugin type name in the format: CompanyName.Namespace.PluginName.
+    /// This is used for plugin resolution, identification, or registration.
+    /// </summary>
+    public string Type => $"{CompanyName}.{Namespace}.{Name}";
+
+    /// <summary>
+    /// Validates that an identifier is non-empty, starts with a letter,
+    /// and contains only letters and digits.
+    /// </summary>
+    /// <param name="input">The string to validate.</param>
+    /// <param name="fieldName">The name of the field being validated, used in the error message.</param>
+    /// <returns>The validated input string.</returns>
+    /// <exception cref="ArgumentException">
+    /// Thrown if the input is null, whitespace, or contains invalid characters.
+    /// </exception>
+    private static string ValidateIdentifier(string input, string fieldName)
+    {
+        if (string.IsNullOrWhiteSpace(input))
+            throw new ArgumentException($"{fieldName} cannot be null or whitespace.");
+
+        if (!ValidIdentifierRegex.IsMatch(input))
+            throw new ArgumentException($"{fieldName} must start with a letter and contain only letters and " +
+                $"digits (no underscores, spaces, or symbols).");
+
+        return input;
+    }
 }

src/FlowSynx.PluginCore/PluginNamespace.cs

@@ -1,8 +1,22 @@
 namespace FlowSynx.PluginCore;
 
+/// <summary>
+/// Defines the logical categorization or role of a plugin within the system.
+/// </summary>
 public enum PluginNamespace
 {
+    /// <summary>
+    /// Represents plugins that contain core business logic or decision-making rules.
+    /// </summary>
     Logics,
+
+    /// <summary>
+    /// Represents plugins that connect to external systems, services, or data sources.
+    /// </summary>
     Connectors,
+
+    /// <summary>
+    /// Represents plugins that modify, transform, or enrich data as it flows through the system.
+    /// </summary>
     Transformers
 }