com.wallstop-studios.dxmessaging 2.1.6 → 2.1.8

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

@@ -1,247 +0,0 @@
----
-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

package/.llm/skills/testing/test-failure-investigation-procedure.md

@@ -1,216 +0,0 @@
----
-title: "Test Failure Investigation Procedure"
-id: "test-failure-investigation-procedure"
-category: "testing"
-version: "1.0.0"
-created: "2026-01-22"
-updated: "2026-01-22"
-
-source:
-  repository: "wallstop/DxMessaging"
-  files:
-    - path: "Tests/Runtime/"
-  url: "https://github.com/wallstop/DxMessaging"
-
-tags:
-  - "testing"
-  - "investigation"
-  - "procedure"
-  - "debugging"
-
-complexity:
-  level: "intermediate"
-  reasoning: "Requires disciplined investigation and data gathering"
-
-impact:
-  performance:
-    rating: "none"
-    details: "Investigation process; no runtime impact"
-  maintainability:
-    rating: "critical"
-    details: "Systematic investigation prevents regressions"
-  testability:
-    rating: "critical"
-    details: "Keeps test suite reliable"
-
-prerequisites:
-  - "Understanding of debugging techniques"
-
-dependencies:
-  packages: []
-  skills:
-    - "test-failure-investigation"
-    - "test-diagnostics"
-
-applies_to:
-  languages:
-    - "C#"
-  frameworks:
-    - "Unity"
-    - ".NET"
-    - "NUnit"
-  versions:
-    unity: ">=2021.3"
-
-aliases:
-  - "Test investigation steps"
-
-related:
-  - "test-failure-investigation"
-  - "test-failure-investigation-root-causes"
-  - "test-diagnostics"
-
-status: "stable"
----
-
-# Test Failure Investigation Procedure
-
-> **One-line summary**: Follow a repeatable investigation process before making any fix.
-
-## Overview
-
-A structured process ensures you identify the real root cause rather than masking symptoms.
-
-## Problem Statement
-
-Ad-hoc fixes often hide underlying issues and produce flaky tests.
-
-## Solution
-
-### Step 1: Reproduce the Failure
-
-Ensure the failure can be reproduced reliably.
-
-```csharp
-// Run the specific failing test multiple times
-// Unity: Window > Test Runner > Right-click test > Run
-// CLI: dotnet test --filter "FullyQualifiedName=Namespace.TestClass.TestMethod"
-
-for i in {1..100}; do
-    echo "Run $i"
-    dotnet test --filter "TestName" || echo "FAILED on run $i"
-done
-```
-
-### Step 2: Understand the Expected Behavior
-
-Document what the test is verifying:
-
-1. What production behavior is being tested?
-1. What are the preconditions?
-1. What is the expected outcome?
-1. Why does this matter to users?
-
-### Step 3: Analyze the Failure
-
-Add diagnostic output to capture actual state at failure.
-
-```csharp
-[Test]
-public void MessageRoutedToCorrectHandler()
-{
-    MessageBus bus = new MessageBus();
-    TestHandler handler1 = new TestHandler();
-    TestHandler handler2 = new TestHandler();
-
-    bus.RegisterTargeted<TestMessage>(handler1, targetId1);
-    bus.RegisterTargeted<TestMessage>(handler2, targetId2);
-
-    bus.SendTargeted(targetId1, new TestMessage());
-
-    UnityEngine.Debug.Log($"Handler1 received: {handler1.ReceivedCount}, Handler2 received: {handler2.ReceivedCount}");
-    UnityEngine.Debug.Log($"Target1: {targetId1}, Target2: {targetId2}");
-    UnityEngine.Debug.Log($"Bus registration count: {bus.GetRegistrationCount()}");
-
-    Assert.AreEqual(1, handler1.ReceivedCount,
-        $"Handler1 should receive exactly 1 message. Target1={targetId1}, Handler1Id={handler1.Id}");
-    Assert.AreEqual(0, handler2.ReceivedCount,
-        $"Handler2 should receive no messages. Target2={targetId2}, Handler2Id={handler2.Id}");
-}
-```
-
-### Step 4: Investigate Production Code
-
-Read the code path the test exercises:
-
-- Check initialization order and assumptions
-- Inspect thread-safety and shared state
-- Identify edge cases the test might trigger
-
-### Step 5: Identify Root Cause
-
-Categorize the failure:
-
-| Category              | Description                         | Example                           |
-| --------------------- | ----------------------------------- | --------------------------------- |
-| **Production Bug**    | Code doesn't behave as intended     | Race condition in message routing |
-| **Test Bug**          | Test has incorrect expectations     | Wrong expected value              |
-| **Test Setup Bug**    | Test doesn't set up state correctly | Missing initialization            |
-| **Order Dependency**  | Test depends on execution order     | Shared static state               |
-| **Timing Issue**      | Test has race conditions            | Async operation not awaited       |
-| **Environment Issue** | Test depends on environment         | File paths, time zones            |
-
-### Step 6: Fix Comprehensively
-
-Fix the actual problem, not the symptom:
-
-```csharp
-// Fix production code for race conditions
-public void Register(IHandler handler)
-{
-    lock (_registrationLock)
-    {
-        _handlers.Add(handler);
-    }
-}
-
-// Fix test expectation after investigation
-[Test]
-public void UnregisteredHandlerReceivesNoMessages()
-{
-    handler.Unregister();
-    bus.Send(new TestMessage());
-
-    Assert.AreEqual(0, handler.ReceivedCount,
-        "Handler should receive no messages after Unregister() returns");
-}
-```
-
-### Step 7: Verify the Fix
-
-- Run the fixed test repeatedly (10x or more)
-- Run related tests to ensure no regressions
-- Run the full suite before committing
-
-```bash
-for i in {1..50}; do dotnet test --filter "TestName" || exit 1; done
-```
-
-### Step 8: Document Findings
-
-Record edge cases or behavior clarifications in code comments or docs.
-
-```csharp
-/// <remarks>
-/// Investigation (2026-01-22): This test was failing intermittently due to
-/// a race condition in handler registration. The fix ensures registration
-/// is atomic. Message delivery order now matches registration order.
-/// </remarks>
-[Test]
-public void HandlersReceiveMessagesInRegistrationOrder()
-{
-    // ...
-}
-```
-
-## See Also
-
-- [Test Failure Investigation](test-failure-investigation.md)
-- [Root Causes and Anti-Patterns](test-failure-investigation-root-causes.md)
-- [Test Diagnostics](test-diagnostics.md)
-
-## Changelog
-
-| Version | Date       | Changes         |
-| ------- | ---------- | --------------- |
-| 1.0.0   | 2026-01-22 | Initial version |

package/.llm/skills/testing/test-failure-investigation-root-causes.md

@@ -1,186 +0,0 @@
----
-title: "Test Failure Root Causes and Anti-Patterns"
-id: "test-failure-investigation-root-causes"
-category: "testing"
-version: "1.0.0"
-created: "2026-01-22"
-updated: "2026-01-22"
-
-source:
-  repository: "wallstop/DxMessaging"
-  files:
-    - path: "Tests/Runtime/"
-  url: "https://github.com/wallstop/DxMessaging"
-
-tags:
-  - "testing"
-  - "root-cause-analysis"
-  - "anti-patterns"
-  - "flaky-tests"
-
-complexity:
-  level: "intermediate"
-  reasoning: "Requires identifying patterns that produce flaky behavior"
-
-impact:
-  performance:
-    rating: "none"
-    details: "Investigation guidance only"
-  maintainability:
-    rating: "critical"
-    details: "Preventing flaky tests keeps the suite trustworthy"
-  testability:
-    rating: "critical"
-    details: "Improves determinism across tests"
-
-prerequisites:
-  - "Understanding of debugging techniques"
-
-dependencies:
-  packages: []
-  skills:
-    - "test-failure-investigation"
-
-applies_to:
-  languages:
-    - "C#"
-  frameworks:
-    - "Unity"
-    - ".NET"
-    - "NUnit"
-  versions:
-    unity: ">=2021.3"
-
-aliases:
-  - "Flaky test causes"
-
-related:
-  - "test-failure-investigation"
-  - "test-failure-investigation-procedure"
-
-status: "stable"
----
-
-# Test Failure Root Causes and Anti-Patterns
-
-> **One-line summary**: Identify common root causes of flaky tests and avoid anti-patterns that hide failures.
-
-## Overview
-
-Most flaky failures fall into a few categories. This guide helps you recognize the pattern and apply the right fix.
-
-## Problem Statement
-
-Treating symptoms instead of causes leads to recurring failures and unreliable CI results.
-
-## Solution
-
-### Timing and Race Conditions
-
-**Symptom**: Test passes locally, fails in CI.
-
-**Investigation**:
-
-- Look for async operations without synchronization
-- Check callbacks that may fire before assertions
-- Inspect thread safety of shared resources
-
-**Fix**:
-
-```csharp
-// BAD: Race between Send and assertion
-bus.SendAsync(message);
-Assert.IsTrue(handler.Received);
-
-// GOOD: Proper synchronization
-bus.Send(message);
-Assert.IsTrue(handler.Received);
-```
-
-### Shared State Between Tests
-
-**Symptom**: Test passes alone, fails with others.
-
-**Fix**:
-
-```csharp
-public class MessageBusTests
-{
-    private MessageBus _bus;
-
-    [SetUp]
-    public void SetUp()
-    {
-        _bus = new MessageBus();
-    }
-
-    [TearDown]
-    public void TearDown()
-    {
-        _bus.Dispose();
-    }
-}
-```
-
-### Order Dependencies
-
-**Symptom**: Tests fail when executed in a different order.
-
-**Fix**: Ensure each test is fully self-contained with no shared static state.
-
-### Unity-Specific Issues
-
-**Symptom**: Test fails only in PlayMode or only in EditMode.
-
-**Fix**:
-
-```csharp
-[UnityTest]
-public IEnumerator ComponentInitializesCorrectly()
-{
-    GameObject go = new GameObject("Test");
-    TestComponent component = go.AddComponent<TestComponent>();
-
-    yield return null;
-
-    Assert.IsTrue(component.IsInitialized,
-        "Component should be initialized after Start()");
-
-    Object.Destroy(go);
-}
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                                 | Why It's Bad                       | What To Do Instead              |
-| -------------------------------------------- | ---------------------------------- | ------------------------------- |
-| `Thread.Sleep()` / `WaitForSeconds()` as fix | Masks timing bugs, slows tests     | Fix the race condition properly |
-| `[Ignore]` attribute                         | Hides real bugs                    | Fix or remove the test          |
-| Retry loops                                  | Masks intermittent failures        | Find and fix root cause         |
-| `try/catch` swallowing                       | Hides exceptions                   | Let exceptions propagate        |
-| "Works on my machine"                        | Different environments expose bugs | Fix for all environments        |
-| Increasing timeouts                          | Slows test suite, masks issues     | Fix the underlying timing       |
-| Deleting failing tests                       | Loses coverage                     | Fix the test                    |
-
-## Investigation Checklist
-
-- [ ] Can I reproduce the failure reliably?
-- [ ] Do I understand the behavior the test verifies?
-- [ ] Have I inspected actual vs expected values?
-- [ ] Have I read the production code path being tested?
-- [ ] Is this a production bug or a test bug?
-- [ ] Are there shared state or order dependencies?
-- [ ] Are there timing/race issues?
-- [ ] Does the fix address the root cause?
-- [ ] Have I run the test multiple times after fixing?
-
-## See Also
-
-- [Test Failure Investigation](test-failure-investigation.md)
-- [Investigation Procedure](test-failure-investigation-procedure.md)
-
-## Changelog
-
-| Version | Date       | Changes         |
-| ------- | ---------- | --------------- |
-| 1.0.0   | 2026-01-22 | Initial version |