feat(v3-batch3): B3-WP4 — {{equip}}/<RefName> reference-relative resolution

Replace the deleted equipment-base-prefix {{equip}} mechanism (impossible now that equipment is reference-only) with per-reference resolution: {{equip}}/<RefName> resolves through the owning equipment's UnsTagReference rows (by effective name) to the backing raw tag's RawPath. Every unresolved <RefName> is a clear deploy error + authoring rejection + Monaco diagnostic — preserving "editor accepts <=> publish accepts". Commons: - EquipmentScriptPaths: delete DeriveEquipmentBase; SubstituteEquipmentToken now takes the equipment's reference map (effectiveName -> RawPath) and substitutes {{equip}}/<RefName> inside path literals (unresolved left intact, never throws); add ExtractEquipReferenceNames (path-literal scoped) + ExtractEquipReferenceNamesFromText (message templates). Slash syntax replaces the v2 dot joint. - New EquipmentReferenceMap: shared, input-shape-agnostic builder (entity + JSON sides) over RawPathResolver — the single authority both compose seams + the validator use, so resolved RawPaths agree byte-for-byte. Compose seams (byte-parity kept): - AddressSpaceComposer.Compose + DeploymentArtifact.ParseComposition both build the per-equipment reference map from UnsTagReferences + Tags + raw topology and substitute VirtualTag AND ScriptedAlarm-predicate sources before dependency extraction (runtime dep refs = resolved RawPaths). Deploy gate + authoring + editor: - DraftValidator.ValidateEquipReferenceResolution: EquipReferenceUnresolved error for unresolved {{equip}}/<RefName> in VirtualTag/ScriptedAlarm scripts + alarm message-template tokens (naming script, equipment, missing ref). - UnsTreeService.ValidateEquipTokenAsync (Wave-A M1): reference-relative authoring rejection, replacing the stale DeriveEquipmentBase(empty)->reject-all logic. - ScriptAnalysisService: {{equip}}/ completion offers the equipment's reference effective names; DiagnoseAsync flags unresolved refs (OTSCRIPT_EQUIPREF) same as the deploy gate. Requests carry optional EquipmentId (threaded MonacoEditor -> monaco-init.js -> fetch bodies). IScriptTagCatalog.GetEquipmentRelativeLeavesAsync repurposed to GetEquipmentReferenceNamesAsync(equipmentId, filter). Tests: EquipmentScriptPaths substitution/extraction (slash pinned); composer<-> artifact reference-resolution byte-parity; DraftValidator unresolved-ref; ScriptAnalysis completion+diagnostic; M1 authoring gate. Build clean (0/0); all five affected suites green. Claude-Session: https://claude.ai/code/session_01LVneM3eh1UtJxEisFXgmox
2026-07-16 06:58:17 -04:00
parent a88dc86173
commit dc0d7653b9
23 changed files with 1142 additions and 426 deletions
@@ -214,6 +214,117 @@ public sealed class DraftValidatorTests
        ScriptId = "s-1",
    };

+    // ------------------------------------------------------------------------------------
+    // ValidateEquipReferenceResolution — v3 WP4: {{equip}}/<RefName> must resolve to a reference
+    // ------------------------------------------------------------------------------------
+
+    private static Script BuildScript(string id, string source) => new()
+    {
+        ScriptId = id, Name = id, SourceCode = source, SourceHash = $"h-{id}",
+    };
+
+    private static Tag BuildRawTag(string tagId, string name) => new()
+    {
+        TagId = tagId, DeviceId = "dev-1", Name = name, DataType = "Float",
+        AccessLevel = TagAccessLevel.Read, TagConfig = "{}",
+    };
+
+    private static UnsTagReference BuildReference(string id, string equipmentId, string tagId, string? overrideName = null) => new()
+    {
+        UnsTagReferenceId = id, EquipmentId = equipmentId, TagId = tagId, DisplayNameOverride = overrideName,
+    };
+
+    /// <summary>A VirtualTag script using <c>{{equip}}/Speed</c> with no reference "Speed" on the equipment is
+    /// a deploy error naming the equipment + the missing ref.</summary>
+    [Fact]
+    public void VirtualTag_equip_ref_unresolved_is_deploy_error()
+    {
+        var draft = new DraftSnapshot
+        {
+            GenerationId = 1, ClusterId = "c",
+            Scripts = [BuildScript("s-1", "return ctx.GetTag(\"{{equip}}/Speed\").Value;")],
+            VirtualTags = [BuildVirtualTag(equipmentId: "eq-1", name: "vt")],
+        };
+
+        var err = DraftValidator.Validate(draft).First(e => e.Code == "EquipReferenceUnresolved");
+        err.Message.ShouldContain("eq-1");
+        err.Message.ShouldContain("Speed");
+    }
+
+    /// <summary>The same script resolves cleanly when the equipment has a reference whose effective name is
+    /// "Speed" (backing raw tag's Name).</summary>
+    [Fact]
+    public void VirtualTag_equip_ref_resolved_is_clean()
+    {
+        var draft = new DraftSnapshot
+        {
+            GenerationId = 1, ClusterId = "c",
+            Scripts = [BuildScript("s-1", "return ctx.GetTag(\"{{equip}}/Speed\").Value;")],
+            VirtualTags = [BuildVirtualTag(equipmentId: "eq-1", name: "vt")],
+            Tags = [BuildRawTag("tag-1", "Speed")],
+            UnsTagReferences = [BuildReference("ref-1", "eq-1", "tag-1")],
+        };
+
+        DraftValidator.Validate(draft).ShouldNotContain(e => e.Code == "EquipReferenceUnresolved");
+    }
+
+    /// <summary>A DisplayNameOverride is the effective name: <c>{{equip}}/MotorSpeed</c> resolves to a
+    /// reference overridden to "MotorSpeed" even though the backing raw tag's Name is "raw_speed".</summary>
+    [Fact]
+    public void VirtualTag_equip_ref_resolves_by_override_name()
+    {
+        var draft = new DraftSnapshot
+        {
+            GenerationId = 1, ClusterId = "c",
+            Scripts = [BuildScript("s-1", "return ctx.GetTag(\"{{equip}}/MotorSpeed\").Value;")],
+            VirtualTags = [BuildVirtualTag(equipmentId: "eq-1", name: "vt")],
+            Tags = [BuildRawTag("tag-1", "raw_speed")],
+            UnsTagReferences = [BuildReference("ref-1", "eq-1", "tag-1", overrideName: "MotorSpeed")],
+        };
+
+        DraftValidator.Validate(draft).ShouldNotContain(e => e.Code == "EquipReferenceUnresolved");
+    }
+
+    /// <summary>A reference on a DIFFERENT equipment does not satisfy the token — resolution is per owning
+    /// equipment.</summary>
+    [Fact]
+    public void VirtualTag_equip_ref_does_not_resolve_across_equipment()
+    {
+        var draft = new DraftSnapshot
+        {
+            GenerationId = 1, ClusterId = "c",
+            Scripts = [BuildScript("s-1", "return ctx.GetTag(\"{{equip}}/Speed\").Value;")],
+            VirtualTags = [BuildVirtualTag(equipmentId: "eq-1", name: "vt")],
+            Tags = [BuildRawTag("tag-1", "Speed")],
+            UnsTagReferences = [BuildReference("ref-1", "eq-2", "tag-1")], // reference is on eq-2, not eq-1
+        };
+
+        DraftValidator.Validate(draft).ShouldContain(e => e.Code == "EquipReferenceUnresolved");
+    }
+
+    /// <summary>Alarm message-template <c>{{equip}}/Temp</c> follows the same rule — an unresolved ref in the
+    /// template is a deploy error.</summary>
+    [Fact]
+    public void ScriptedAlarm_message_template_equip_ref_unresolved_is_deploy_error()
+    {
+        var draft = new DraftSnapshot
+        {
+            GenerationId = 1, ClusterId = "c",
+            Scripts = [BuildScript("s-1", "return true;")],
+            ScriptedAlarms =
+            [
+                new ScriptedAlarm
+                {
+                    ScriptedAlarmId = "al-1", EquipmentId = "eq-1", Name = "overheat",
+                    AlarmType = "LimitAlarm", MessageTemplate = "Too hot: {{equip}}/Temp",
+                    PredicateScriptId = "s-1",
+                },
+            ],
+        };
+
+        DraftValidator.Validate(draft).ShouldContain(e => e.Code == "EquipReferenceUnresolved");
+    }
+
    // ------------------------------------------------------------------------------------
    // Phase 6.3 task #148 part 2 — ValidateClusterTopology (unchanged in v3)
    // ------------------------------------------------------------------------------------