feat(driver-twincat): shared TagConfigJson readers, writable key, Inspect warnings (R2-11)

archreview/plans/R2-11-tagconfig-consolidation-plan.md.tasks.json

@@ -17,7 +17,7 @@
     { "id": "T13", "subject": "S7 equipment-tag parser: freeze test, shared readers, honour writable key, Inspect warnings (+ amend Contracts banner)", "status": "completed", "blockedBy": ["T11"] },
     { "id": "T14", "subject": "AbCip equipment-tag parser: freeze test, shared readers (writable already honoured), Inspect warnings", "status": "completed", "blockedBy": ["T11"] },
     { "id": "T15", "subject": "AbLegacy equipment-tag parser: freeze test, shared readers, honour writable key, Inspect warnings", "status": "completed", "blockedBy": ["T11"] },
-    { "id": "T16", "subject": "TwinCAT equipment-tag parser: freeze test, shared readers, honour writable key, Inspect warnings", "status": "pending", "blockedBy": ["T11"] },
+    { "id": "T16", "subject": "TwinCAT equipment-tag parser: freeze test, shared readers, honour writable key, Inspect warnings", "status": "completed", "blockedBy": ["T11"] },
     { "id": "T17", "subject": "FOCAS equipment-tag parser: force Writable:false (05/UNDER-1 correction), shared readers, Inspect warnings (+ amend Contracts banner)", "status": "pending", "blockedBy": ["T11"] },
     { "id": "T18", "subject": "FOCAS capability-matrix pre-flight on the equipment-tag _parseRef resolve path (BadNodeIdUnknown on rejection)", "status": "pending", "blockedBy": ["T17"] },
     { "id": "T19", "subject": "Modbus probe parses the factory DTO shape (timeoutMs round-trip; OpcUaClient parity rule)", "status": "pending", "blockedBy": [] },

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Contracts/TwinCATEquipmentTagParser.cs

@@ -1,4 +1,5 @@
 using System.Text.Json;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
 
 namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
 
@@ -28,15 +29,18 @@ public static class TwinCATEquipmentTagParser
             var symbolPath = symbol.GetString();
             if (string.IsNullOrWhiteSpace(symbolPath)) return false;
             var deviceHostAddress = ReadString(root, "deviceHostAddress");
-            var dataType = ReadEnum(root, "dataType", TwinCATDataType.DInt);
+            var dataType = TagConfigJson.ReadEnumOrDefault(root, "dataType", TwinCATDataType.DInt);
             // Array intent — same shape the runtime/OPC-UA foundation parses (camelCase
             // `isArray` bool + `arrayLength` uint). arrayLength is honoured ONLY when isArray
             // is true AND it is a positive JSON number, so a stale length behind a cleared
             // isArray never produces an orphan array tag (Phase 4c).
             var arrayLength = ReadArrayLength(root);
+            // "writable" defaults to true when absent (today's value) — makes read-only equipment tags
+            // authorable (UNDER-6).
+            var writable = TagConfigJson.ReadWritable(root);
             def = new TwinCATTagDefinition(
                 Name: reference, DeviceHostAddress: deviceHostAddress, SymbolPath: symbolPath,
-                DataType: dataType, Writable: true, ArrayLength: arrayLength);
+                DataType: dataType, Writable: writable, ArrayLength: arrayLength);
             return true;
         }
         catch (JsonException) { return false; }
@@ -44,9 +48,35 @@ public static class TwinCATEquipmentTagParser
         catch (InvalidOperationException) { return false; }
     }
 
-    private static TEnum ReadEnum<TEnum>(JsonElement o, string name, TEnum fallback) where TEnum : struct, Enum
-        => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.String
-           && Enum.TryParse<TEnum>(e.GetString(), ignoreCase: true, out var v) ? v : fallback;
+    /// <summary>
+    ///     Deploy-time inspection (05/CONV-2): warns on a present-but-invalid <c>dataType</c> (silently
+    ///     defaulted by the lenient runtime) and on a structurally unparseable TagConfig. Empty when clean
+    ///     or not an equipment-tag object. Never throws.
+    /// </summary>
+    /// <param name="reference">The equipment tag's TagConfig JSON.</param>
+    /// <returns>The warnings; empty when clean.</returns>
+    public static IReadOnlyList<string> Inspect(string reference)
+    {
+        var warnings = new List<string>();
+        if (string.IsNullOrWhiteSpace(reference) || reference[0] != '{') return warnings;
+        try
+        {
+            using var doc = JsonDocument.Parse(reference);
+            var root = doc.RootElement;
+            if (root.ValueKind != JsonValueKind.Object)
+            {
+                warnings.Add("TwinCAT TagConfig root is not a JSON object — the tag will not resolve (BadNodeIdUnknown).");
+                return warnings;
+            }
+            var w = TagConfigJson.DescribeInvalidEnum<TwinCATDataType>(root, "dataType");
+            if (w is not null) warnings.Add(w);
+        }
+        catch (JsonException)
+        {
+            warnings.Add("TwinCAT TagConfig is not valid JSON — the tag will not resolve (BadNodeIdUnknown).");
+        }
+        return warnings;
+    }
 
     private static string ReadString(JsonElement o, string name)
         => o.TryGetProperty(name, out var e) && e.ValueKind == JsonValueKind.String

src/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Contracts/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Contracts.csproj

@@ -5,5 +5,9 @@
         <ImplicitUsings>enable</ImplicitUsings>
         <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
     </PropertyGroup>
-    <!-- NO PackageReference. -->
+    <!-- NO PackageReference. ProjectReference only to the zero-dependency Core.Abstractions leaf
+         (R2-11 05/CONV-2 — shared TagConfigJson readers). -->
+    <ItemGroup>
+        <ProjectReference Include="..\..\Core\ZB.MOM.WW.OtOpcUa.Core.Abstractions\ZB.MOM.WW.OtOpcUa.Core.Abstractions.csproj"/>
+    </ItemGroup>
 </Project>

tests/Drivers/ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests/TwinCATEquipmentTagParserStrictnessTests.cs

@@ -0,0 +1,49 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.TwinCAT;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.TwinCAT.Tests;
+
+/// <summary>R2-11 (05/CONV-2) strictness surface for the TwinCAT equipment-tag parser: lenient runtime
+/// freeze, <c>Inspect</c> reports the typo, and the <c>writable</c> key is honoured (default true).</summary>
+public sealed class TwinCATEquipmentTagParserStrictnessTests
+{
+    [Fact]
+    public void Freeze_typo_dataType_still_defaults_to_DInt()
+    {
+        TwinCATEquipmentTagParser.TryParse("{\"symbolPath\":\"MAIN.x\",\"dataType\":\"DIntt\"}", out var def)
+            .ShouldBeTrue();
+        def.DataType.ShouldBe(TwinCATDataType.DInt);
+    }
+
+    [Fact]
+    public void Inspect_reports_typo_dataType()
+    {
+        var warnings = TwinCATEquipmentTagParser.Inspect("{\"symbolPath\":\"MAIN.x\",\"dataType\":\"DIntt\"}");
+        warnings.ShouldHaveSingleItem();
+        warnings[0].ShouldContain("DIntt");
+        warnings[0].ShouldContain("dataType");
+    }
+
+    [Fact]
+    public void Inspect_clean_config_has_no_warnings()
+    {
+        TwinCATEquipmentTagParser.Inspect("{\"symbolPath\":\"MAIN.x\",\"dataType\":\"DInt\"}").ShouldBeEmpty();
+    }
+
+    [Fact]
+    public void Writable_false_is_honoured()
+    {
+        TwinCATEquipmentTagParser.TryParse("{\"symbolPath\":\"MAIN.x\",\"dataType\":\"DInt\",\"writable\":false}", out var def)
+            .ShouldBeTrue();
+        def.Writable.ShouldBeFalse();
+    }
+
+    [Fact]
+    public void Writable_absent_defaults_to_true()
+    {
+        TwinCATEquipmentTagParser.TryParse("{\"symbolPath\":\"MAIN.x\",\"dataType\":\"DInt\"}", out var def)
+            .ShouldBeTrue();
+        def.Writable.ShouldBeTrue();
+    }
+}