Refactor plugin architecture for extensibility

Replaced `PluginSpecifications` with `IPluginSpecifications` for a more structured and type-safe approach. Updated `IPlugin` to support operations, asynchronous initialization, and improved specification handling. Introduced `IPluginOperation` for strongly-typed operations.

Simplified `ReflectionHelper.IsCalledViaReflection` to avoid test infrastructure interference. Added `OperationParameterMetadataAttribute` and `SpecificationMetadataAttribute` for enhanced metadata handling.

Refactored `PluginParameters` and `PluginSpecifications` to improve validation and dynamic property mapping. Removed `RequiredMemberAttribute` and its tests. Updated tests to align with the new architecture. General cleanup and modernization to improve maintainability.

#26

Author: ziagham

src/Extensions/PluginSpecificationsExtensions.cs

@@ -6,21 +6,8 @@ public static class ReflectionHelper
 {
     public static bool IsCalledViaReflection()
     {
-        var stack = new StackTrace();
-        var frames = stack.GetFrames();
-
-        if (frames == null)
-            return false;
-
-        foreach (var frame in frames)
-        {
-            var callingMethod = frame.GetMethod();
-            if (callingMethod == null) continue;
-
-            if (callingMethod.DeclaringType?.Namespace?.StartsWith("System.Reflection") == true)
-                return true;
-        }
-
-        return false;
+        // Check only the immediate caller to avoid xUnit/testhost infrastructure
+        var callingMethod = new StackFrame(1).GetMethod();
+        return callingMethod?.DeclaringType?.Namespace?.StartsWith("System.Reflection") == true;
     }
 }

src/Helpers/ReflectionHelper.cs

@@ -1,46 +1,17 @@
 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; }
+    IPluginSpecifications? Specifications { get; }
+    IReadOnlyCollection<IPluginOperation> SupportedOperations { get; }
 
-    /// <summary>
-    /// Gets or sets the plugin-specific configuration or specifications used during execution.
-    /// </summary>
-    PluginSpecifications? Specifications { get; set; }
+    Task InitializeAsync(
+        IPluginLogger logger,
+        IDictionary<string, object?>? specifications);
 
-    /// <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>
-    /// Gets the set of supported operation names.
-    /// </summary>
-    /// <remarks>
-    /// Operation names are case-insensitive and typically represent actions such as "create", "read", "update", or "delete".
-    /// </remarks>
-    IReadOnlyCollection<string> SupportedOperations { 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);
+    Task<object?> ExecuteAsync(
+        string? operationName,
+        PluginParameters parameters,
+        CancellationToken cancellationToken);
 }

src/IPlugin.cs

@@ -0,0 +1,12 @@
+namespace FlowSynx.PluginCore;
+
+public interface IPluginOperation
+{
+    string Name { get; }
+    string Description { get; }
+}
+
+public interface IPluginOperation<TParameters, TResult> : IPluginOperation
+{
+    Task<TResult?> ExecuteAsync(TParameters parameters, CancellationToken cancellationToken);
+}

src/IPluginOperation.cs

@@ -0,0 +1,14 @@
+namespace FlowSynx.PluginCore;
+
+public interface IPluginSpecifications
+{
+    /// <summary>
+    /// Validate the specification values.
+    /// </summary>
+    void Validate();
+
+    /// <summary>
+    /// Load values from a dictionary dynamically.
+    /// </summary>
+    void FromDictionary(IDictionary<string, object?> dict);
+}

src/IPluginSpecifications.cs

@@ -0,0 +1,15 @@
+namespace FlowSynx.PluginCore;
+
+[AttributeUsage(AttributeTargets.Property, Inherited = false)]
+public class OperationParameterMetadataAttribute : Attribute
+{
+    /// <summary>
+    /// Gets the description of the parameter.
+    /// </summary>
+    public string Description { get; set; } = null!;
+
+    /// <summary>
+    /// Gets a value indicating whether the parameter is required.
+    /// </summary>
+    public bool IsRequired { get; set; } = false;
+}

src/OperationParameterMetadataAttribute.cs

@@ -9,11 +9,20 @@ public class PluginParameters : Dictionary<string, object?>, ICloneable
     /// <summary>
     /// Initializes a new instance of the <see cref="PluginParameters"/> class
     /// with the contents of an existing dictionary. Keys are compared case-insensitively.
+    /// Filters out reserved keys like `OperationName`.
     /// </summary>
     /// <param name="dictionary">The dictionary whose elements are copied to the new instance.</param>
     public PluginParameters(IDictionary<string, object?> dictionary)
-        : base(dictionary, StringComparer.OrdinalIgnoreCase)
+        : base(StringComparer.OrdinalIgnoreCase)
     {
+        // Copy only non-reserved keys
+        foreach (var kvp in dictionary)
+        {
+            if (!string.Equals(kvp.Key, "OperationName", StringComparison.OrdinalIgnoreCase))
+            {
+                this[kvp.Key] = kvp.Value;
+            }
+        }
     }
 
     /// <summary>
@@ -32,7 +41,11 @@ public PluginParameters()
     /// <returns>A shallow copy of the current instance.</returns>
     public object Clone()
     {
-        var clone = (PluginParameters)MemberwiseClone();
+        var clone = new PluginParameters();
+        foreach (var kvp in this)
+        {
+            clone[kvp.Key] = kvp.Value; // shallow copy of values
+        }
         return clone;
     }
 }

src/PluginParameters.cs

@@ -1,38 +1,73 @@
 namespace FlowSynx.PluginCore;
 
-/// <summary>
-/// Represents a case-insensitive dictionary of specifications or configuration values for a plugin.
-/// Implements <see cref="ICloneable"/> for shallow cloning.
-/// </summary>
-public class PluginSpecifications : Dictionary<string, object?>, ICloneable
+public abstract class PluginSpecifications : IPluginSpecifications
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="PluginSpecifications"/> class
-    /// using the specified dictionary. Keys are compared case-insensitively.
+    /// Validate the specification values
     /// </summary>
-    /// <param name="dictionary">The dictionary whose elements are copied to the new instance.</param>
-    public PluginSpecifications(IDictionary<string, object?> dictionary)
-        : base(dictionary, StringComparer.OrdinalIgnoreCase)
-    {
-    }
+    public abstract void Validate();
 
     /// <summary>
-    /// Initializes a new, empty instance of the <see cref="PluginSpecifications"/> class.
-    /// Keys are compared case-insensitively.
+    /// Load values from a dictionary dynamically
     /// </summary>
-    public PluginSpecifications()
-        : base(StringComparer.OrdinalIgnoreCase)
+    /// <param name="dict">Dictionary of parameter values</param>
+    public virtual void FromDictionary(IDictionary<string, object?> dict)
     {
-    }
+        // Default implementation using reflection
+        var properties = this.GetType().GetProperties()
+            .Where(p => p.CanWrite)
+            .ToDictionary(p => p.Name, p => p);
 
-    /// <summary>
-    /// Creates a shallow copy of the current <see cref="PluginSpecifications"/> instance.
-    /// Note: The values in the dictionary are not deep-cloned.
-    /// </summary>
-    /// <returns>A shallow copy of the current instance.</returns>
-    public object Clone()
-    {
-        var clone = (PluginSpecifications)MemberwiseClone();
-        return clone;
+        foreach (var kvp in dict)
+        {
+            if (properties.TryGetValue(kvp.Key, out var prop))
+            {
+                var value = kvp.Value;
+                if (value == null)
+                    continue;
+
+                var targetType = prop.PropertyType;
+                var valueType = value.GetType();
+
+                if (targetType.IsAssignableFrom(valueType))
+                {
+                    prop.SetValue(this, value);
+                    continue;
+                }
+
+                try
+                {
+                    object converted;
+                    if (targetType == typeof(DateTime) && value is string s)
+                    {
+                        // Preserve Kind from roundtrip (ISO 8601) strings.
+                        converted = DateTime.Parse(s, System.Globalization.CultureInfo.InvariantCulture, System.Globalization.DateTimeStyles.RoundtripKind);
+                    }
+                    else if (targetType == typeof(bool) && value is string sb)
+                    {
+                        converted = bool.Parse(sb);
+                    }
+                    else if (targetType == typeof(int) && value is string si)
+                    {
+                        converted = int.Parse(si, System.Globalization.CultureInfo.InvariantCulture);
+                    }
+                    else if (targetType == typeof(double) && value is string sd)
+                    {
+                        converted = double.Parse(sd, System.Globalization.CultureInfo.InvariantCulture);
+                    }
+                    else
+                    {
+                        converted = Convert.ChangeType(value, targetType, System.Globalization.CultureInfo.InvariantCulture);
+                    }
+
+                    prop.SetValue(this, converted);
+                }
+                catch
+                {
+                    // Rethrow to preserve original behavior of failing on invalid conversion
+                    throw;
+                }
+            }
+        }
     }
 }

src/PluginSpecifications.cs

@@ -0,0 +1,18 @@
+namespace FlowSynx.PluginCore;
+
+/// <summary>
+/// Describes a single specification definition for a plugin.
+/// </summary>
+[AttributeUsage(AttributeTargets.Property, Inherited = false)]
+public sealed class SpecificationMetadataAttribute : Attribute
+{
+    /// <summary>
+    /// Gets the optional textual description associated with the object.
+    /// </summary>
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// True if the user must explicitly provide this value.
+    /// </summary>
+    public bool IsRequired { get; set; } = false;
+}