com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

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

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

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

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

@@ -0,0 +1,119 @@
+---
+title: "Test Failure Investigation and Zero-Flaky Policy"
+id: "test-failure-investigation"
+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"
+  - "debugging"
+  - "quality"
+  - "zero-flaky"
+  - "root-cause-analysis"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires systematic debugging skills and understanding of production behavior"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Investigation process; no runtime impact"
+  maintainability:
+    rating: "critical"
+    details: "Ensures codebase quality and prevents hidden bugs"
+  testability:
+    rating: "critical"
+    details: "Maintains test suite reliability and trustworthiness"
+
+prerequisites:
+  - "Understanding of debugging techniques"
+  - "Familiarity with the codebase under test"
+
+dependencies:
+  packages: []
+  skills:
+    - "test-diagnostics"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+    - "NUnit"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Flaky test investigation"
+  - "Test debugging"
+  - "Root cause analysis"
+  - "Zero-flaky policy"
+
+related:
+  - "test-diagnostics"
+  - "test-base-class-cleanup"
+  - "test-categories"
+  - "test-failure-investigation-procedure"
+  - "test-failure-investigation-root-causes"
+
+status: "stable"
+---
+
+# Test Failure Investigation and Zero-Flaky Policy
+
+> **One-line summary**: Every test failure reveals a real bug - investigate production behavior comprehensively before making any fix.
+
+## Overview
+
+This project maintains a **zero-flaky test policy**. A flaky test is one that sometimes passes and sometimes fails without code changes. We do not tolerate flaky tests because they hide real bugs and erode trust in the test suite.
+
+### Every test failure must be treated as a production bug until proven otherwise
+
+## Problem Statement
+
+Ignoring or masking test failures leads to unreliable tests, hidden regressions, and broken production behavior.
+
+## Solution
+
+### Core Principles
+
+1. **All test failures indicate bugs**: Production or test code - both require fixes.
+1. **No superficial fixes**: Never "make the test pass" without understanding why it failed.
+1. **No ignored tests**: Do not use `[Ignore]`, `[Skip]`, or commented-out tests to hide failures.
+1. **Full investigation required**: Find the root cause before making changes.
+1. **Document discoveries**: Captured edge cases become institutional knowledge.
+
+### High-Level Investigation Flow
+
+1. Reproduce the failure reliably
+1. Understand expected behavior and assertions
+1. Inspect production code paths
+1. Identify root cause (production vs test)
+1. Fix comprehensively and verify repeatedly
+
+## Summary
+
+A passing test suite should mean the code works correctly. A failing test should mean there is a real problem to fix. This trust is essential for effective development.
+
+## See Also
+
+- [Investigation Procedure](test-failure-investigation-procedure.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-invalid-skill.md

@@ -0,0 +1,26 @@
+---
+title: "Test Invalid Skill"
+id: "test-invalid-skill"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-22"
+updated: "2026-01-22"
+status: "stable"
+
+complexity:
+  level: "expert"
+
+impact:
+  performance:
+    rating: "high"
+  maintainability:
+    rating: "high"
+---
+
+## Overview
+
+Test skill with invalid values.
+
+## Solution
+
+Test solution.

package/.lychee.toml

@@ -24,5 +24,7 @@ exclude = [
   "^https?://0\\.0\\.0\\.0",
   "^file://",
   # NPM package page serves a Cloudflare JS challenge to non-browser clients; registry endpoint remains covered.
-  "^https://www\\.npmjs\\.com/package/com\\.wallstop-studios\\.dxmessaging$"
+  "^https://www\\.npmjs\\.com/package/com\\.wallstop-studios\\.dxmessaging$",
+  # GitHub Pages site - not deployed yet, will be available after first successful deploy
+  "^https://wallstop\\.github\\.io/DxMessaging"
 ]

package/.markdownlint.json

@@ -10,6 +10,8 @@
   "MD046": { "style": "fenced" },
   // Duplicate headings only matter among siblings
   "MD024": { "siblings_only": true },
+  // Allow frontmatter title plus a top-level heading
+  "MD025": { "front_matter_title": "" },
   // Allow uniform '1.' numbering (matches Prettier behavior)
   "MD029": { "style": "one" },
   // Permit bare URLs; Prettier won’t auto-wrap, and link checks are handled separately

package/.markdownlint.jsonc

@@ -10,6 +10,8 @@
   "MD046": { "style": "fenced" },
   // Duplicate headings only matter among siblings
   "MD024": { "siblings_only": true },
+  // Allow frontmatter title plus a top-level heading
+  "MD025": { "front_matter_title": "" },
   // Allow uniform '1.' numbering (matches Prettier behavior)
   "MD029": { "style": "one" },
   // Permit bare URLs; Prettier won’t auto-wrap, and link checks are handled separately

package/.markdownlintignore

@@ -1,7 +1,7 @@
-node_modules/
-.git/
-Library/
-obj/
-Temp/
-Samples~/
-/.github/
+node_modules/
+.git/
+Library/
+obj/
+Temp/
+Samples~/
+/.github/