com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/testing/test-diagnostics-patterns.md

@@ -0,0 +1,189 @@
+---
+title: "Test Diagnostics Patterns"
+id: "test-diagnostics-patterns"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "logging"
+  - "debugging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on diagnostic collector usage"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics add minor overhead when enabled"
+  maintainability:
+    rating: "high"
+    details: "Improves failure investigation"
+  testability:
+    rating: "high"
+    details: "Makes failures easier to reproduce"
+
+prerequisites:
+  - "Understanding of test diagnostics"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+
+aliases:
+  - "Test diagnostics patterns"
+
+related:
+  - "test-diagnostics"
+
+status: "stable"
+---
+
+# Test Diagnostics Patterns
+
+> **One-line summary**: Toggleable diagnostics and edge-case markers for test debugging.
+
+## Overview
+
+This skill documents toggleable diagnostics and edge-case markers.
+
+## Solution
+
+Apply the patterns below to collect targeted diagnostics safely.
+
+### Toggleable Diagnostics Pattern
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Diagnostics
+{
+    using UnityEngine;
+
+    /// <summary>
+    /// Zero-overhead diagnostics with name filtering.
+    /// </summary>
+    internal static class EditorDiagnostics
+    {
+        /// <summary>
+        /// Enable/disable all diagnostics.
+        /// </summary>
+        internal static bool Enabled { get; set; } = false;
+
+        /// <summary>
+        /// Only log for components matching this filter (null = all).
+        /// </summary>
+        internal static string NameFilter { get; set; }
+
+        private const string LogPrefix = "[Diagnostics] ";
+
+        private static bool ShouldLog(string name)
+        {
+            if (!Enabled) return false;
+
+            if (!string.IsNullOrEmpty(NameFilter))
+            {
+                if (name == null) return false;
+                if (name.IndexOf(NameFilter, System.StringComparison.OrdinalIgnoreCase) < 0)
+                    return false;
+            }
+
+            return true;
+        }
+
+        internal static void Log(string name, string message)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.Log($"{LogPrefix}[{name}] {message}");
+        }
+
+        internal static void LogFormat(string name, string format, params object[] args)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.LogFormat($"{LogPrefix}[{name}] {format}", args);
+        }
+
+        internal static void LogStateChange(string name, string from, string to)
+        {
+            if (!ShouldLog(name)) return;
+            Debug.Log($"{LogPrefix}[{name}] State: {from} -> {to}");
+        }
+
+        internal static void LogMethodEntry(string name, string method, string parameters = null)
+        {
+            if (!ShouldLog(name)) return;
+            string msg = string.IsNullOrEmpty(parameters)
+                ? $"-> {method}()"
+                : $"-> {method}({parameters})";
+            Debug.Log($"{LogPrefix}[{name}] {msg}");
+        }
+
+        internal static void LogMethodExit(string name, string method, object result = null)
+        {
+            if (!ShouldLog(name)) return;
+            string msg = result == null
+                ? $"<- {method}()"
+                : $"<- {method}() = {result}";
+            Debug.Log($"{LogPrefix}[{name}] {msg}");
+        }
+    }
+}
+```
+
+### Intentional Edge Case Markers
+
+```csharp
+/// <summary>
+/// Marker comments for test linter to ignore intentional patterns.
+/// </summary>
+public static class TestMarkers
+{
+    // Comment pattern: // UNH-SUPPRESS: <reason>
+    //
+    // Used when tests intentionally do things that would trigger warnings:
+    // - DestroyImmediate in tests
+    // - Null access testing
+    // - Exception testing
+}
+
+// Usage in tests:
+[Test]
+public void GetGameObjectHandlesDestroyedComponent()
+{
+    GameObject go = CreateGameObject("Test");
+    SpriteRenderer sr = go.AddComponent<SpriteRenderer>();
+
+    // UNH-SUPPRESS: Test verifies behavior after intentional destruction
+    Object.DestroyImmediate(sr);
+
+    // Should handle destroyed component gracefully
+    GameObject result = sr.GetGameObject();
+    Assert.IsTrue(result == null);
+}
+
+[Test]
+public void HandleNullGracefully()
+{
+    // UNH-SUPPRESS: Intentional null testing
+    string nullString = null;
+
+    Assert.DoesNotThrow(() => processor.Process(nullString));
+}
+```

package/.llm/skills/testing/test-diagnostics-usage.md

@@ -0,0 +1,196 @@
+---
+title: "Test Diagnostics Usage"
+id: "test-diagnostics-usage"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "logging"
+  - "debugging"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Builds on diagnostic collector usage"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics add minor overhead when enabled"
+  maintainability:
+    rating: "high"
+    details: "Improves failure investigation"
+  testability:
+    rating: "high"
+    details: "Makes failures easier to reproduce"
+
+prerequisites:
+  - "Understanding of test diagnostics"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+
+aliases:
+  - "Test diagnostics patterns"
+
+related:
+  - "test-diagnostics"
+
+status: "stable"
+---
+
+# Test Diagnostics Usage
+
+> **One-line summary**: How to apply diagnostics in tests, with performance guidance.
+
+## Overview
+
+This skill explains how to use diagnostics in tests and CI.
+
+## Solution
+
+Follow the guidance below to enable diagnostics without noise.
+
+## Usage
+
+### Using Diagnostics in Tests
+
+```csharp
+[TestFixture]
+public sealed class SpatialQueryTests : CommonTestBase
+{
+    [Test]
+    public void QueryReturnsAllPointsInBounds()
+    {
+        // Enable diagnostics for this test
+        var diagnostics = new SpatialQueryDiagnosticsCollector();
+        tree.SetQueryLogger(diagnostics);
+
+        // Setup
+        var points = new List<Vector3>();
+        for (int i = 0; i < 100; i++)
+        {
+            var point = Random.insideUnitSphere * 10;
+            points.Add(point);
+            tree.Insert(point);
+        }
+
+        // Query
+        Bounds queryBounds = new Bounds(Vector3.zero, Vector3.one * 5);
+        diagnostics.BeginQuery(queryBounds);
+        var results = tree.Query(queryBounds);
+
+        // Calculate expected
+        var expected = points.Where(p => queryBounds.Contains(p)).ToList();
+
+        // Assert with diagnostics on failure
+        if (results.Count != expected.Count)
+        {
+            string report = diagnostics.BuildReport(expected, results);
+            Assert.Fail($"Query returned wrong count.\n\n{report}");
+        }
+
+        Assert.AreEqual(expected.Count, results.Count);
+    }
+}
+```
+
+### Enabling Diagnostics for Debugging
+
+```csharp
+[TestFixture]
+public sealed class StateMachineTests : CommonTestBase
+{
+    [SetUp]
+    public override void CommonSetUp()
+    {
+        base.CommonSetUp();
+
+        // Enable diagnostics for this specific component
+        EditorDiagnostics.Enabled = true;
+        EditorDiagnostics.NameFilter = "PlayerStateMachine";
+    }
+
+    [TearDown]
+    public override void TearDown()
+    {
+        EditorDiagnostics.Enabled = false;
+        EditorDiagnostics.NameFilter = null;
+        base.TearDown();
+    }
+
+    [Test]
+    public void TransitionsCorrectly()
+    {
+        // Now all PlayerStateMachine logs will appear
+        stateMachine.TransitionTo(State.Running);
+    }
+}
+```
+
+## Performance Notes
+
+- **Disabled Diagnostics**: Zero overhead (early return before string formatting)
+- **Enabled Diagnostics**: ~1us per log call
+- **Collectors**: Memory proportional to events collected
+
+## Best Practices
+
+### Do
+
+- Disable diagnostics by default
+- Use collectors for complex algorithms (spatial, pathfinding)
+- Include all relevant context in diagnostic reports
+- Use consistent prefixes for log filtering
+- Document UNH-SUPPRESS markers with reasons
+
+### Don't
+
+- Don't leave diagnostics enabled in production
+- Don't collect unbounded data (limit with maxItems)
+- Don't use diagnostics for simple pass/fail tests
+- Don't suppress warnings without documenting why
+
+### Diagnostic Collector Template
+
+```csharp
+public sealed class MyAlgorithmDiagnostics
+{
+    private readonly List<StepRecord> _steps = new List<StepRecord>();
+
+    public void RecordStep(string description, object state)
+    {
+        _steps.Add(new StepRecord(description, state.ToString()));
+    }
+
+    public string BuildReport()
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("=== ALGORITHM TRACE ===");
+        foreach (var step in _steps)
+        {
+            sb.AppendLine($"[{step.Index}] {step.Description}: {step.State}");
+        }
+        return sb.ToString();
+    }
+}
+```

package/.llm/skills/testing/test-diagnostics.md

@@ -0,0 +1,247 @@
+---
+title: "Test Diagnostics and Investigation Patterns"
+id: "test-diagnostics"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SpatialDiagnosticsCollector.cs"
+    - path: "Runtime/Core/Diagnostics/WGroupIndentDiagnostics.cs"
+      lines: "24-130"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "diagnostics"
+  - "debugging"
+  - "logging"
+  - "investigation"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of diagnostic patterns and test investigation"
+
+impact:
+  performance:
+    rating: "low"
+    details: "Diagnostics disabled by default; zero overhead when off"
+  maintainability:
+    rating: "high"
+    details: "Helps understand complex test failures"
+  testability:
+    rating: "high"
+    details: "Enables deep investigation of failing tests"
+
+prerequisites:
+  - "Understanding of debugging techniques"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Test logging"
+  - "Diagnostic collector"
+  - "Test investigation"
+
+related:
+  - "test-base-class-cleanup"
+  - "test-categories"
+  - "test-diagnostics-patterns"
+  - "test-diagnostics-usage"
+
+status: "stable"
+---
+
+# Test Diagnostics and Investigation Patterns
+
+> **One-line summary**: Implement diagnostic collectors and toggleable logging to understand complex test failures without polluting normal test output.
+
+## Overview
+
+When tests fail in complex systems (spatial queries, state machines, algorithms), stack traces aren't enough. This pattern provides:
+
+1. **Diagnostic Collectors**: Record detailed execution traces
+1. **Toggleable Diagnostics**: Zero overhead when disabled
+1. **Filtered Logging**: Focus on specific components
+1. **Investigation Markers**: Document intentional edge cases
+
+## Problem Statement
+
+```csharp
+// BAD: Test fails with unhelpful message
+[Test]
+public void SpatialQueryReturnsNearbyObjects()
+{
+    tree.Insert(point1);
+    tree.Insert(point2);
+    // ...
+    var results = tree.Query(bounds);
+
+    Assert.AreEqual(5, results.Count); // Fails: Expected 5, got 3
+    // WHY? Which points were missed? What did the query visit?
+}
+```
+
+## Solution
+
+### Diagnostic Collector Pattern
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests.Diagnostics
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Text;
+    using UnityEngine;
+
+    /// <summary>
+    /// Records detailed trace of spatial query execution for debugging.
+    /// </summary>
+    public sealed class SpatialQueryDiagnosticsCollector : IOctTreeQueryLogger
+    {
+        public struct NodeVisit
+        {
+            public Bounds NodeBounds;
+            public int PointCount;
+            public bool FullyContained;
+            public bool Intersects;
+            public VisitResult Result;
+        }
+
+        public enum VisitResult { Skipped, Partial, Full }
+
+        private readonly List<NodeVisit> _nodeVisits = new List<NodeVisit>(64);
+        private readonly List<Vector3> _pointsEvaluated = new List<Vector3>(128);
+        private readonly List<Vector3> _pointsIncluded = new List<Vector3>(64);
+        private readonly List<Vector3> _pointsExcluded = new List<Vector3>(64);
+        private Bounds _queryBounds;
+
+        public void BeginQuery(Bounds queryBounds)
+        {
+            _queryBounds = queryBounds;
+            _nodeVisits.Clear();
+            _pointsEvaluated.Clear();
+            _pointsIncluded.Clear();
+            _pointsExcluded.Clear();
+        }
+
+        public void LogNodeVisit(Bounds nodeBounds, int pointCount, bool fullyContained, bool intersects, VisitResult result)
+        {
+            _nodeVisits.Add(new NodeVisit
+            {
+                NodeBounds = nodeBounds,
+                PointCount = pointCount,
+                FullyContained = fullyContained,
+                Intersects = intersects,
+                Result = result
+            });
+        }
+
+        public void LogPointEvaluated(Vector3 point, bool included)
+        {
+            _pointsEvaluated.Add(point);
+            if (included)
+                _pointsIncluded.Add(point);
+            else
+                _pointsExcluded.Add(point);
+        }
+
+        /// <summary>
+        /// Build a detailed report for test failure investigation.
+        /// </summary>
+        public string BuildReport(
+            ICollection<Vector3> expected,
+            ICollection<Vector3> actual,
+            int maxItems = 32)
+        {
+            StringBuilder sb = new StringBuilder(2048);
+
+            sb.AppendLine("=== SPATIAL QUERY DIAGNOSTICS ===");
+            sb.AppendLine();
+            sb.AppendLine($"Query Bounds: {_queryBounds}");
+            sb.AppendLine($"Expected Count: {expected.Count}");
+            sb.AppendLine($"Actual Count: {actual.Count}");
+            sb.AppendLine();
+
+            // Missing points
+            var missing = new HashSet<Vector3>(expected);
+            foreach (var p in actual) missing.Remove(p);
+
+            if (missing.Count > 0)
+            {
+                sb.AppendLine($"MISSING POINTS ({missing.Count}):");
+                int shown = 0;
+                foreach (var p in missing)
+                {
+                    if (shown++ >= maxItems) { sb.AppendLine("  ..."); break; }
+                    bool inBounds = _queryBounds.Contains(p);
+                    sb.AppendLine($"  {p} (in bounds: {inBounds})");
+                }
+                sb.AppendLine();
+            }
+
+            // Extra points
+            var extra = new HashSet<Vector3>(actual);
+            foreach (var p in expected) extra.Remove(p);
+
+            if (extra.Count > 0)
+            {
+                sb.AppendLine($"EXTRA POINTS ({extra.Count}):");
+                int shown = 0;
+                foreach (var p in extra)
+                {
+                    if (shown++ >= maxItems) { sb.AppendLine("  ..."); break; }
+                    sb.AppendLine($"  {p}");
+                }
+                sb.AppendLine();
+            }
+
+            // Node visit summary
+            sb.AppendLine($"NODE VISITS ({_nodeVisits.Count}):");
+            int skipped = 0, partial = 0, full = 0;
+            foreach (var visit in _nodeVisits)
+            {
+                switch (visit.Result)
+                {
+                    case VisitResult.Skipped: skipped++; break;
+                    case VisitResult.Partial: partial++; break;
+                    case VisitResult.Full: full++; break;
+                }
+            }
+            sb.AppendLine($"  Skipped: {skipped}, Partial: {partial}, Full: {full}");
+            sb.AppendLine();
+
+            // Sample node visits
+            sb.AppendLine("SAMPLE NODE VISITS:");
+            for (int i = 0; i < Math.Min(6, _nodeVisits.Count); i++)
+            {
+                var v = _nodeVisits[i];
+                sb.AppendLine($"  [{v.Result}] points={v.PointCount} contained={v.FullyContained} intersects={v.Intersects}");
+            }
+
+            return sb.ToString();
+        }
+    }
+}
+```
+
+## Related Patterns
+
+- [Test Base Class Cleanup](./test-base-class-cleanup.md) - Test infrastructure
+- [Test Categories](./test-categories.md) - Organizing diagnostic tests
+- [Test Diagnostics Patterns](./test-diagnostics-patterns.md) - Toggleable and edge-case diagnostics
+- [Test Diagnostics Usage](./test-diagnostics-usage.md) - Applying diagnostics in tests