Phase 0 WP-0.2–0.9: Implement Commons (types, entities, interfaces, messages, protocol, tests)

- WP-0.2: Namespace/folder skeleton (26 directories) - WP-0.3: Shared data types (6 enums, RetryPolicy, Result<T>) - WP-0.4: 24 domain entity POCOs across 10 domain areas - WP-0.5: 7 repository interfaces with full CRUD signatures - WP-0.6: IAuditService cross-cutting interface - WP-0.7: 26 message contract records across 8 concern areas - WP-0.8: IDataConnection protocol abstraction with batch ops - WP-0.9: 8 architectural constraint enforcement tests All 40 tests pass, zero warnings.
2026-03-16 18:48:24 -04:00
parent fed5f5a82c
commit 22e1eba58a
78 changed files with 1530 additions and 16 deletions
--- a/tests/ScadaLink.Commons.Tests/ArchitecturalConstraintTests.cs
+++ b/tests/ScadaLink.Commons.Tests/ArchitecturalConstraintTests.cs
@@ -0,0 +1,187 @@
+using System.Reflection;
+using System.Xml.Linq;
+
+namespace ScadaLink.Commons.Tests;
+
+public class ArchitecturalConstraintTests
+{
+    private static readonly Assembly CommonsAssembly = typeof(ScadaLink.Commons.Types.RetryPolicy).Assembly;
+
+    private static string GetCsprojPath()
+    {
+        // Walk up from test output to find the Commons csproj
+        var dir = new DirectoryInfo(AppContext.BaseDirectory);
+        while (dir != null)
+        {
+            var candidate = Path.Combine(dir.FullName, "src", "ScadaLink.Commons", "ScadaLink.Commons.csproj");
+            if (File.Exists(candidate))
+                return candidate;
+            dir = dir.Parent;
+        }
+        throw new InvalidOperationException("Could not find ScadaLink.Commons.csproj");
+    }
+
+    private static string GetCommonsSourceDirectory()
+    {
+        var csproj = GetCsprojPath();
+        return Path.GetDirectoryName(csproj)!;
+    }
+
+    [Fact]
+    public void Csproj_ShouldNotHaveForbiddenPackageReferences()
+    {
+        var csprojPath = GetCsprojPath();
+        var doc = XDocument.Load(csprojPath);
+        var ns = doc.Root!.GetDefaultNamespace();
+
+        var forbiddenPrefixes = new[] { "Akka.", "Microsoft.AspNetCore.", "Microsoft.EntityFrameworkCore." };
+
+        var packageRefs = doc.Descendants(ns + "PackageReference")
+            .Select(e => e.Attribute("Include")?.Value)
+            .Where(v => v != null)
+            .ToList();
+
+        foreach (var pkg in packageRefs)
+        {
+            foreach (var prefix in forbiddenPrefixes)
+            {
+                Assert.False(pkg!.StartsWith(prefix, StringComparison.OrdinalIgnoreCase),
+                    $"Commons has forbidden package reference: {pkg}");
+            }
+        }
+    }
+
+    [Fact]
+    public void Assembly_ShouldNotReferenceForbiddenAssemblies()
+    {
+        var forbiddenPrefixes = new[] { "Akka.", "Microsoft.AspNetCore.", "Microsoft.EntityFrameworkCore." };
+
+        var referencedAssemblies = CommonsAssembly.GetReferencedAssemblies();
+
+        foreach (var asmName in referencedAssemblies)
+        {
+            foreach (var prefix in forbiddenPrefixes)
+            {
+                Assert.False(asmName.Name!.StartsWith(prefix, StringComparison.OrdinalIgnoreCase),
+                    $"Commons references forbidden assembly: {asmName.Name}");
+            }
+        }
+    }
+
+    [Fact]
+    public void Commons_ShouldNotContainServiceOrActorImplementations()
+    {
+        // Heuristic: class has > 3 public non-property methods that are not constructors
+        var types = CommonsAssembly.GetTypes()
+            .Where(t => t.IsClass && !t.IsAbstract && !t.IsInterface);
+
+        foreach (var type in types)
+        {
+            var publicMethods = type.GetMethods(BindingFlags.Public | BindingFlags.Instance | BindingFlags.DeclaredOnly)
+                .Where(m => !m.IsSpecialName) // excludes property getters/setters
+                .Where(m => !m.Name.StartsWith("<")) // excludes compiler-generated
+                .Where(m => m.Name != "ToString" && m.Name != "GetHashCode" &&
+                            m.Name != "Equals" && m.Name != "Deconstruct" &&
+                            m.Name != "PrintMembers" && m.Name != "GetType")
+                .ToList();
+
+            Assert.True(publicMethods.Count <= 3,
+                $"Type {type.FullName} has {publicMethods.Count} public methods ({string.Join(", ", publicMethods.Select(m => m.Name))}), which suggests it may contain service/actor logic");
+        }
+    }
+
+    [Fact]
+    public void SourceFiles_ShouldNotContainToLocalTime()
+    {
+        var sourceDir = GetCommonsSourceDirectory();
+        var csFiles = Directory.GetFiles(sourceDir, "*.cs", SearchOption.AllDirectories);
+
+        foreach (var file in csFiles)
+        {
+            var content = File.ReadAllText(file);
+            Assert.DoesNotContain("ToLocalTime()", content);
+        }
+    }
+
+    [Fact]
+    public void AllEntities_ShouldHaveNoEfAttributes()
+    {
+        var efAttributeNames = new HashSet<string>
+        {
+            "KeyAttribute", "ForeignKeyAttribute", "TableAttribute",
+            "ColumnAttribute", "RequiredAttribute", "MaxLengthAttribute",
+            "StringLengthAttribute", "DatabaseGeneratedAttribute",
+            "NotMappedAttribute", "IndexAttribute", "InversePropertyAttribute"
+        };
+
+        var entityTypes = CommonsAssembly.GetTypes()
+            .Where(t => t.IsClass && !t.IsAbstract && t.Namespace != null
+                        && t.Namespace.Contains(".Entities."));
+
+        foreach (var type in entityTypes)
+        {
+            foreach (var attr in type.GetCustomAttributes(true))
+            {
+                Assert.DoesNotContain(attr.GetType().Name, efAttributeNames);
+            }
+
+            foreach (var prop in type.GetProperties())
+            {
+                foreach (var attr in prop.GetCustomAttributes(true))
+                {
+                    Assert.False(efAttributeNames.Contains(attr.GetType().Name),
+                        $"{type.Name}.{prop.Name} has EF attribute {attr.GetType().Name}");
+                }
+            }
+        }
+    }
+
+    [Fact]
+    public void AllEnums_ShouldBeSingularNamed()
+    {
+        var enums = CommonsAssembly.GetTypes().Where(t => t.IsEnum);
+
+        foreach (var enumType in enums)
+        {
+            var name = enumType.Name;
+            // Singular names should not end with 's' (except words ending in 'ss' or 'us' which are singular)
+            Assert.False(name.EndsWith("s") && !name.EndsWith("ss") && !name.EndsWith("us"),
+                $"Enum {name} appears to be plural");
+        }
+    }
+
+    [Fact]
+    public void AllMessageTypes_ShouldBeRecords()
+    {
+        var messageTypes = CommonsAssembly.GetTypes()
+            .Where(t => t.Namespace != null
+                        && t.Namespace.Contains(".Messages.")
+                        && !t.IsEnum && !t.IsInterface
+                        && (t.IsClass || (t.IsValueType && !t.IsPrimitive)));
+
+        foreach (var type in messageTypes)
+        {
+            var cloneMethod = type.GetMethod("<Clone>$", BindingFlags.Public | BindingFlags.Instance);
+            Assert.True(cloneMethod != null,
+                $"{type.FullName} in Messages namespace should be a record type");
+        }
+    }
+
+    [Fact]
+    public void KeyEntities_ShouldHaveDateTimeOffsetTimestamps()
+    {
+        // Spot-check key entity timestamp properties
+        var deploymentRecord = CommonsAssembly.GetType("ScadaLink.Commons.Entities.Deployment.DeploymentRecord");
+        Assert.NotNull(deploymentRecord);
+        Assert.Equal(typeof(DateTimeOffset), deploymentRecord!.GetProperty("DeployedAt")!.PropertyType);
+        Assert.Equal(typeof(DateTimeOffset?), deploymentRecord.GetProperty("CompletedAt")!.PropertyType);
+
+        var artifactRecord = CommonsAssembly.GetType("ScadaLink.Commons.Entities.Deployment.SystemArtifactDeploymentRecord");
+        Assert.NotNull(artifactRecord);
+        Assert.Equal(typeof(DateTimeOffset), artifactRecord!.GetProperty("DeployedAt")!.PropertyType);
+
+        var auditEntry = CommonsAssembly.GetType("ScadaLink.Commons.Entities.Audit.AuditLogEntry");
+        Assert.NotNull(auditEntry);
+        Assert.Equal(typeof(DateTimeOffset), auditEntry!.GetProperty("Timestamp")!.PropertyType);
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/Entities/EntityConventionTests.cs
+++ b/tests/ScadaLink.Commons.Tests/Entities/EntityConventionTests.cs
@@ -0,0 +1,89 @@
+using System.Collections;
+using System.Reflection;
+
+namespace ScadaLink.Commons.Tests.Entities;
+
+public class EntityConventionTests
+{
+    private static readonly Assembly CommonsAssembly = typeof(ScadaLink.Commons.Types.RetryPolicy).Assembly;
+
+    private static IEnumerable<Type> GetEntityTypes() =>
+        CommonsAssembly.GetTypes()
+            .Where(t => t.IsClass && !t.IsAbstract && t.Namespace != null
+                        && t.Namespace.Contains(".Entities."));
+
+    [Fact]
+    public void AllEntities_ShouldHaveNoEfAttributes()
+    {
+        var efAttributeNames = new HashSet<string>
+        {
+            "KeyAttribute", "ForeignKeyAttribute", "TableAttribute",
+            "ColumnAttribute", "RequiredAttribute", "MaxLengthAttribute",
+            "StringLengthAttribute", "DatabaseGeneratedAttribute",
+            "NotMappedAttribute", "IndexAttribute", "InversePropertyAttribute"
+        };
+
+        foreach (var entityType in GetEntityTypes())
+        {
+            // Check class-level attributes
+            var classAttrs = entityType.GetCustomAttributes(true);
+            foreach (var attr in classAttrs)
+            {
+                Assert.DoesNotContain(attr.GetType().Name, efAttributeNames);
+            }
+
+            // Check property-level attributes
+            foreach (var prop in entityType.GetProperties())
+            {
+                var propAttrs = prop.GetCustomAttributes(true);
+                foreach (var attr in propAttrs)
+                {
+                    Assert.False(efAttributeNames.Contains(attr.GetType().Name),
+                        $"Entity {entityType.Name}.{prop.Name} has EF attribute {attr.GetType().Name}");
+                }
+            }
+        }
+    }
+
+    [Fact]
+    public void AllTimestampProperties_ShouldBeDateTimeOffset()
+    {
+        var timestampNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
+        {
+            "Timestamp", "DeployedAt", "CompletedAt", "GeneratedAt",
+            "ReportTimestamp", "SnapshotTimestamp"
+        };
+
+        foreach (var entityType in GetEntityTypes())
+        {
+            foreach (var prop in entityType.GetProperties())
+            {
+                if (timestampNames.Contains(prop.Name))
+                {
+                    var underlyingType = Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType;
+                    Assert.True(underlyingType == typeof(DateTimeOffset),
+                        $"{entityType.Name}.{prop.Name} should be DateTimeOffset but is {prop.PropertyType.Name}");
+                }
+            }
+        }
+    }
+
+    [Fact]
+    public void NavigationProperties_ShouldBeICollection()
+    {
+        foreach (var entityType in GetEntityTypes())
+        {
+            foreach (var prop in entityType.GetProperties())
+            {
+                if (prop.PropertyType.IsGenericType &&
+                    typeof(IEnumerable).IsAssignableFrom(prop.PropertyType) &&
+                    prop.PropertyType != typeof(string))
+                {
+                    Assert.True(
+                        prop.PropertyType.GetGenericTypeDefinition() == typeof(ICollection<>),
+                        $"{entityType.Name}.{prop.Name} should be ICollection<T> but is {prop.PropertyType.Name}");
+                }
+            }
+        }
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/Messages/MessageConventionTests.cs
+++ b/tests/ScadaLink.Commons.Tests/Messages/MessageConventionTests.cs
@@ -0,0 +1,130 @@
+using System.Reflection;
+using System.Text.Json;
+
+namespace ScadaLink.Commons.Tests.Messages;
+
+public class MessageConventionTests
+{
+    private static readonly Assembly CommonsAssembly = typeof(ScadaLink.Commons.Types.RetryPolicy).Assembly;
+
+    private static IEnumerable<Type> GetMessageTypes() =>
+        CommonsAssembly.GetTypes()
+            .Where(t => t.Namespace != null
+                        && t.Namespace.Contains(".Messages.")
+                        && !t.IsEnum
+                        && !t.IsInterface
+                        && (t.IsClass || (t.IsValueType && !t.IsPrimitive)));
+
+    [Fact]
+    public void AllMessageTypes_ShouldBeRecords()
+    {
+        foreach (var type in GetMessageTypes())
+        {
+            // Records have a compiler-generated <Clone>$ method
+            var cloneMethod = type.GetMethod("<Clone>$", BindingFlags.Public | BindingFlags.Instance);
+            Assert.True(cloneMethod != null,
+                $"{type.FullName} in Messages namespace should be a record type");
+        }
+    }
+
+    [Fact]
+    public void AllMessageTimestampProperties_ShouldBeDateTimeOffset()
+    {
+        foreach (var type in GetMessageTypes())
+        {
+            foreach (var prop in type.GetProperties())
+            {
+                if (prop.Name.Contains("Timestamp") || prop.Name == "GeneratedAt" || prop.Name == "DeployedAt")
+                {
+                    var underlyingType = Nullable.GetUnderlyingType(prop.PropertyType) ?? prop.PropertyType;
+                    Assert.True(underlyingType == typeof(DateTimeOffset),
+                        $"{type.Name}.{prop.Name} should be DateTimeOffset but is {prop.PropertyType.Name}");
+                }
+            }
+        }
+    }
+
+    [Fact]
+    public void JsonRoundTrip_DeployInstanceCommand_ShouldSucceed()
+    {
+        var msg = new ScadaLink.Commons.Messages.Deployment.DeployInstanceCommand(
+            "dep-1", "instance-1", "abc123", "{}", "admin", DateTimeOffset.UtcNow);
+
+        var json = JsonSerializer.Serialize(msg);
+        var deserialized = JsonSerializer.Deserialize<ScadaLink.Commons.Messages.Deployment.DeployInstanceCommand>(json);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal(msg.DeploymentId, deserialized!.DeploymentId);
+        Assert.Equal(msg.InstanceUniqueName, deserialized.InstanceUniqueName);
+    }
+
+    [Fact]
+    public void JsonForwardCompatibility_UnknownField_ShouldDeserialize()
+    {
+        // Simulate a newer version with an extra field
+        var json = """{"DeploymentId":"dep-1","InstanceUniqueName":"inst-1","RevisionHash":"abc","FlattenedConfigurationJson":"{}","DeployedBy":"admin","Timestamp":"2025-01-01T00:00:00+00:00","NewField":"extra"}""";
+
+        var deserialized = JsonSerializer.Deserialize<ScadaLink.Commons.Messages.Deployment.DeployInstanceCommand>(json);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal("dep-1", deserialized!.DeploymentId);
+    }
+
+    [Fact]
+    public void JsonBackwardCompatibility_MissingOptionalField_ShouldDeserialize()
+    {
+        // DeploymentStatusResponse has nullable ErrorMessage
+        var json = """{"DeploymentId":"dep-1","InstanceUniqueName":"inst-1","Status":2,"Timestamp":"2025-01-01T00:00:00+00:00"}""";
+
+        var deserialized = JsonSerializer.Deserialize<ScadaLink.Commons.Messages.Deployment.DeploymentStatusResponse>(json);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal("dep-1", deserialized!.DeploymentId);
+        Assert.Null(deserialized.ErrorMessage);
+    }
+
+    [Fact]
+    public void JsonRoundTrip_SiteHealthReport_ShouldSucceed()
+    {
+        var msg = new ScadaLink.Commons.Messages.Health.SiteHealthReport(
+            "site-1", 1, DateTimeOffset.UtcNow,
+            new Dictionary<string, ScadaLink.Commons.Types.Enums.ConnectionHealth>
+            {
+                ["conn1"] = ScadaLink.Commons.Types.Enums.ConnectionHealth.Connected
+            },
+            new Dictionary<string, ScadaLink.Commons.Messages.Health.TagResolutionStatus>
+            {
+                ["conn1"] = new(10, 8)
+            },
+            0, 0,
+            new Dictionary<string, int> { ["queue1"] = 5 },
+            0);
+
+        var json = JsonSerializer.Serialize(msg);
+        var deserialized = JsonSerializer.Deserialize<ScadaLink.Commons.Messages.Health.SiteHealthReport>(json);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal("site-1", deserialized!.SiteId);
+        Assert.Equal(1, deserialized.SequenceNumber);
+    }
+
+    [Fact]
+    public void JsonRoundTrip_DeployArtifactsCommand_ShouldSucceed()
+    {
+        var msg = new ScadaLink.Commons.Messages.Artifacts.DeployArtifactsCommand(
+            "dep-1",
+            new List<ScadaLink.Commons.Messages.Artifacts.SharedScriptArtifact>
+            {
+                new("script1", "code", null, null)
+            },
+            null, null, null,
+            DateTimeOffset.UtcNow);
+
+        var json = JsonSerializer.Serialize(msg);
+        var deserialized = JsonSerializer.Deserialize<ScadaLink.Commons.Messages.Artifacts.DeployArtifactsCommand>(json);
+
+        Assert.NotNull(deserialized);
+        Assert.Equal("dep-1", deserialized!.DeploymentId);
+        Assert.Single(deserialized.SharedScripts!);
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/Types/EnumTests.cs
+++ b/tests/ScadaLink.Commons.Tests/Types/EnumTests.cs
@@ -0,0 +1,36 @@
+using ScadaLink.Commons.Types.Enums;
+
+namespace ScadaLink.Commons.Tests.Types;
+
+public class EnumTests
+{
+    [Theory]
+    [InlineData(typeof(DataType), new[] { "Boolean", "Int32", "Float", "Double", "String", "DateTime", "Binary" })]
+    [InlineData(typeof(InstanceState), new[] { "Enabled", "Disabled" })]
+    [InlineData(typeof(DeploymentStatus), new[] { "Pending", "InProgress", "Success", "Failed" })]
+    [InlineData(typeof(AlarmState), new[] { "Active", "Normal" })]
+    [InlineData(typeof(AlarmTriggerType), new[] { "ValueMatch", "RangeViolation", "RateOfChange" })]
+    [InlineData(typeof(ConnectionHealth), new[] { "Connected", "Disconnected", "Connecting", "Error" })]
+    public void Enum_ShouldHaveExpectedValues(Type enumType, string[] expectedNames)
+    {
+        var actualNames = Enum.GetNames(enumType);
+        Assert.Equal(expectedNames, actualNames);
+    }
+
+    [Theory]
+    [InlineData(typeof(DataType))]
+    [InlineData(typeof(InstanceState))]
+    [InlineData(typeof(DeploymentStatus))]
+    [InlineData(typeof(AlarmState))]
+    [InlineData(typeof(AlarmTriggerType))]
+    [InlineData(typeof(ConnectionHealth))]
+    public void Enum_ShouldBeSingularNamed(Type enumType)
+    {
+        // Singular names should not end with 's' (except 'Status' which is singular)
+        var name = enumType.Name;
+        Assert.False(name.EndsWith("es") && !name.EndsWith("Status"),
+            $"Enum {name} appears to be plural (ends with 'es').");
+        Assert.False(name.EndsWith("s") && !name.EndsWith("ss") && !name.EndsWith("us"),
+            $"Enum {name} appears to be plural (ends with 's').");
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/Types/ResultTests.cs
+++ b/tests/ScadaLink.Commons.Tests/Types/ResultTests.cs
@@ -0,0 +1,75 @@
+using ScadaLink.Commons.Types;
+
+namespace ScadaLink.Commons.Tests.Types;
+
+public class ResultTests
+{
+    [Fact]
+    public void Success_ShouldCreateSuccessfulResult()
+    {
+        var result = Result<int>.Success(42);
+
+        Assert.True(result.IsSuccess);
+        Assert.False(result.IsFailure);
+        Assert.Equal(42, result.Value);
+    }
+
+    [Fact]
+    public void Failure_ShouldCreateFailedResult()
+    {
+        var result = Result<int>.Failure("something went wrong");
+
+        Assert.True(result.IsFailure);
+        Assert.False(result.IsSuccess);
+        Assert.Equal("something went wrong", result.Error);
+    }
+
+    [Fact]
+    public void Value_OnFailure_ShouldThrow()
+    {
+        var result = Result<int>.Failure("error");
+
+        Assert.Throws<InvalidOperationException>(() => result.Value);
+    }
+
+    [Fact]
+    public void Error_OnSuccess_ShouldThrow()
+    {
+        var result = Result<int>.Success(42);
+
+        Assert.Throws<InvalidOperationException>(() => result.Error);
+    }
+
+    [Fact]
+    public void Match_OnSuccess_ShouldCallOnSuccess()
+    {
+        var result = Result<int>.Success(42);
+
+        var output = result.Match(
+            v => $"value={v}",
+            e => $"error={e}");
+
+        Assert.Equal("value=42", output);
+    }
+
+    [Fact]
+    public void Match_OnFailure_ShouldCallOnFailure()
+    {
+        var result = Result<int>.Failure("bad");
+
+        var output = result.Match(
+            v => $"value={v}",
+            e => $"error={e}");
+
+        Assert.Equal("error=bad", output);
+    }
+
+    [Fact]
+    public void Success_WithNullableReferenceType_ShouldWork()
+    {
+        var result = Result<string>.Success("hello");
+
+        Assert.True(result.IsSuccess);
+        Assert.Equal("hello", result.Value);
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/Types/RetryPolicyTests.cs
+++ b/tests/ScadaLink.Commons.Tests/Types/RetryPolicyTests.cs
@@ -0,0 +1,35 @@
+using ScadaLink.Commons.Types;
+
+namespace ScadaLink.Commons.Tests.Types;
+
+public class RetryPolicyTests
+{
+    [Fact]
+    public void RetryPolicy_ShouldBeImmutableRecord()
+    {
+        var policy = new RetryPolicy(3, TimeSpan.FromSeconds(5));
+
+        Assert.Equal(3, policy.MaxRetries);
+        Assert.Equal(TimeSpan.FromSeconds(5), policy.Delay);
+    }
+
+    [Fact]
+    public void RetryPolicy_WithExpression_ShouldCreateNewInstance()
+    {
+        var original = new RetryPolicy(3, TimeSpan.FromSeconds(5));
+        var modified = original with { MaxRetries = 5 };
+
+        Assert.Equal(3, original.MaxRetries);
+        Assert.Equal(5, modified.MaxRetries);
+        Assert.Equal(original.Delay, modified.Delay);
+    }
+
+    [Fact]
+    public void RetryPolicy_EqualValues_ShouldBeEqual()
+    {
+        var a = new RetryPolicy(3, TimeSpan.FromSeconds(5));
+        var b = new RetryPolicy(3, TimeSpan.FromSeconds(5));
+
+        Assert.Equal(a, b);
+    }
+}
--- a/tests/ScadaLink.Commons.Tests/UnitTest1.cs
+++ b/tests/ScadaLink.Commons.Tests/UnitTest1.cs
@@ -1,10 +0,0 @@
-namespace ScadaLink.Commons.Tests;
-
-public class UnitTest1
-{
-    [Fact]
-    public void Test1()
-    {
-
-    }
-}