com.wallstop-studios.dxmessaging 2.1.5 → 2.1.7

package/.llm/skills/testing/test-production-code.md

@@ -0,0 +1,348 @@
+---
+title: "Test Production Code Directly"
+id: "test-production-code"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-30"
+updated: "2026-01-30"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "scripts/__tests__/"
+    - path: "scripts/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "testing"
+  - "anti-patterns"
+  - "code-quality"
+  - "javascript"
+  - "maintainability"
+  - "testability"
+  - "best-practices"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of test design principles and code architecture"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Testing patterns only; no runtime performance impact"
+  maintainability:
+    rating: "critical"
+    details: "Prevents tests from diverging from production behavior"
+  testability:
+    rating: "critical"
+    details: "Ensures tests actually verify production code correctness"
+
+prerequisites:
+  - "Understanding of module exports and imports"
+  - "Familiarity with test isolation principles"
+
+dependencies:
+  packages: []
+  skills:
+    - "comprehensive-test-coverage"
+    - "script-test-coverage"
+
+applies_to:
+  languages:
+    - "JavaScript"
+    - "TypeScript"
+    - "C#"
+  frameworks:
+    - "Jest"
+    - "Node.js"
+    - "NUnit"
+  versions:
+    node: ">=18.0"
+    jest: ">=29.0"
+
+aliases:
+  - "Test real code"
+  - "Don't re-implement in tests"
+  - "Test production directly"
+  - "Avoid test duplication"
+
+related:
+  - "comprehensive-test-coverage"
+  - "script-test-coverage"
+  - "test-code-quality"
+
+status: "stable"
+---
+
+# Test Production Code Directly
+
+> **One-line summary**: Tests must import and use production code, never re-implement production logic locally.
+
+## Overview
+
+A common anti-pattern in testing is re-implementing production validation logic inside test files. When tests maintain their own copies of validation rules, they can pass even when production code regresses. This skill documents how to structure code for testability and avoid this dangerous pattern.
+
+## Problem Statement
+
+### The Anti-Pattern
+
+Tests that re-implement production logic create a false sense of security:
+
+```javascript
+// PRODUCTION: scripts/validate-data.js
+function validateRecord(record) {
+  const errors = [];
+  if (!record.name || record.name.length < 3) {
+    errors.push("Name must be at least 3 characters");
+  }
+  if (!record.email || !record.email.includes("@")) {
+    errors.push("Email must be valid");
+  }
+  return errors;
+}
+
+// TEST: scripts/__tests__/validate-data.test.js
+// WRONG: Re-implementing validation locally
+function localValidateRecord(record) {
+  const errors = [];
+  if (!record.name || record.name.length < 3) {
+    // Duplicated logic!
+    errors.push("Name must be at least 3 characters");
+  }
+  if (!record.email || !record.email.includes("@")) {
+    // Duplicated logic!
+    errors.push("Email must be valid");
+  }
+  return errors;
+}
+
+test("should validate record correctly", () => {
+  const result = localValidateRecord({ name: "Jo", email: "bad" });
+  expect(result).toHaveLength(2); // Tests pass, but production untested!
+});
+```
+
+### Why This Is Dangerous
+
+1. **Production regressions go undetected**: If someone changes `< 3` to `< 2` in production, tests still pass because they use the local copy.
+1. **Maintenance burden doubles**: Every production change requires updating test copies.
+1. **Divergence over time**: Local test copies gradually drift from production reality.
+1. **False confidence**: 100% test coverage means nothing if tests don't exercise production code.
+1. **Bug duplication**: If the same bug exists in both copies, tests won't catch it.
+
+## Solution
+
+### Structure Production Code for Testability
+
+Export validation functions and helper logic so tests can import them:
+
+```javascript
+// PRODUCTION: scripts/validate-data.js
+/**
+ * Validates a record and returns any errors.
+ * @param {Object} record - The record to validate
+ * @returns {string[]} Array of error messages
+ */
+function validateRecord(record) {
+  const errors = [];
+  if (!isValidName(record.name)) {
+    errors.push("Name must be at least 3 characters");
+  }
+  if (!isValidEmail(record.email)) {
+    errors.push("Email must be valid");
+  }
+  return errors;
+}
+
+/**
+ * Validates name length.
+ * @param {string} name - The name to validate
+ * @returns {boolean} True if valid
+ */
+function isValidName(name) {
+  return name && name.length >= 3;
+}
+
+/**
+ * Validates email format.
+ * @param {string} email - The email to validate
+ * @returns {boolean} True if valid
+ */
+function isValidEmail(email) {
+  return email && email.includes("@");
+}
+
+// Export everything tests need
+module.exports = {
+  validateRecord,
+  isValidName,
+  isValidEmail
+};
+```
+
+### Test Production Code Directly
+
+Import and test the actual production functions:
+
+```javascript
+// TEST: scripts/__tests__/validate-data.test.js
+// CORRECT: Import production code
+const { validateRecord, isValidName, isValidEmail } = require("../validate-data");
+
+describe("validateRecord", () => {
+  test("should return no errors for valid record", () => {
+    const result = validateRecord({ name: "John", email: "john@example.com" });
+    expect(result).toHaveLength(0);
+  });
+
+  test("should return error for short name", () => {
+    const result = validateRecord({ name: "Jo", email: "john@example.com" });
+    expect(result).toContain("Name must be at least 3 characters");
+  });
+
+  test("should return error for invalid email", () => {
+    const result = validateRecord({ name: "John", email: "invalid" });
+    expect(result).toContain("Email must be valid");
+  });
+});
+
+describe("isValidName", () => {
+  test("should accept names with 3 or more characters", () => {
+    expect(isValidName("Joe")).toBe(true);
+    expect(isValidName("John")).toBe(true);
+  });
+
+  test("should reject names with fewer than 3 characters", () => {
+    expect(isValidName("Jo")).toBe(false);
+    expect(isValidName("J")).toBe(false);
+  });
+
+  test("should reject null and undefined", () => {
+    expect(isValidName(null)).toBe(false);
+    expect(isValidName(undefined)).toBe(false);
+  });
+});
+```
+
+## When Local Test Helpers Are Acceptable
+
+Not all code in test files is duplication. These are legitimate uses:
+
+### Thin Wrappers for Test Convenience
+
+```javascript
+// ACCEPTABLE: Thin wrapper that delegates to production
+function validateAndExpectErrors(record, expectedCount) {
+  const result = validateRecord(record); // Calls production!
+  expect(result).toHaveLength(expectedCount);
+  return result;
+}
+```
+
+### Test-Only Utilities
+
+```javascript
+// ACCEPTABLE: Test data generators
+function createValidRecord(overrides = {}) {
+  return {
+    name: "Default Name",
+    email: "default@example.com",
+    ...overrides
+  };
+}
+
+// ACCEPTABLE: Custom matchers
+function expectValidationError(result, expectedMessage) {
+  expect(result.some((msg) => msg.includes(expectedMessage))).toBe(true);
+}
+
+// ACCEPTABLE: Factories for test data
+const TestRecords = {
+  valid: { name: "John Doe", email: "john@example.com" },
+  invalidName: { name: "X", email: "john@example.com" }
+};
+```
+
+## Handling Unavoidable Duplication
+
+Some situations require maintaining parallel implementations. Use SYNC notes to keep them aligned.
+
+### PowerShell Scripts with JavaScript Tests
+
+When the production script is PowerShell but tests are JavaScript:
+
+```powershell
+# PRODUCTION: scripts/validate-data.ps1
+# SYNC: Keep validation logic in sync with validate-data.test.js validateRecord()
+function Test-Record {
+    param([hashtable]$Record)
+    $errors = @()
+    if (-not $Record.name -or $Record.name.Length -lt 3) {
+        $errors += "Name must be at least 3 characters"
+    }
+    return $errors
+}
+```
+
+```javascript
+// TEST: scripts/__tests__/validate-data.test.js
+// SYNC: Keep validation logic in sync with validate-data.ps1 Test-Record
+function validateRecord(record) {
+  const errors = [];
+  if (!record.name || record.name.length < 3) {
+    errors += "Name must be at least 3 characters";
+  }
+  return errors;
+}
+```
+
+### Browser-Only Code
+
+When code runs only in browsers and cannot be tested in Node.js:
+
+```javascript
+// PRODUCTION: browser-only.js (uses DOM APIs)
+// SYNC: Core logic duplicated for testing in browser-only.test.js
+
+// TEST: browser-only.test.js
+// SYNC: Keep validation logic in sync with browser-only.js computeLayout()
+// This is a test-only implementation because production uses DOM APIs
+```
+
+## SYNC Note Best Practices
+
+When duplication is unavoidable, follow these SYNC note guidelines:
+
+1. **Always bidirectional**: Both files must reference each other
+1. **Never use line numbers**: Reference function names, not line numbers that change
+1. **Use descriptive identifiers**: `SYNC: Keep in sync with validate.js isValidEmail()` not `SYNC: Keep in sync with validate.js line 42`
+1. **Verify references exist**: Confirm the referenced function exists before adding the note
+1. **Update both on changes**: When modifying synced code, update both locations
+
+## Red Flags to Watch For
+
+These patterns suggest tests may not be exercising production code:
+
+| Red Flag                                               | Why It's Suspicious           |
+| ------------------------------------------------------ | ----------------------------- |
+| Test file defines validation constants                 | Should import from production |
+| Test file has utility functions that mirror production | Should import instead         |
+| Test never imports the module it's supposedly testing  | Tests itself, not production  |
+| Test file size rivals production file size             | Too much duplicated logic     |
+| Same bug exists in production and tests                | Copied code with copied bugs  |
+
+## Verification Checklist
+
+Before merging, verify tests exercise production code:
+
+1. **Check imports**: Does the test file import from the production module?
+1. **Check coverage**: Does production file show coverage when tests run?
+1. **Mutation test**: Change production code slightly - do tests fail?
+1. **Review test functions**: Are they calling production code or local copies?
+1. **Search for duplication**: Do test and production files have similar function bodies?
+
+## See Also
+
+- [Comprehensive Test Coverage skill](comprehensive-test-coverage.md) - What to test
+- [Script Test Coverage skill](script-test-coverage.md) - Testing scripts specifically
+- [Test Code Quality skill](test-code-quality.md) - Test documentation accuracy

package/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.7]
+
+### Changed
+
+- Improved README with prominent Mental Model section
+- Added Mermaid diagrams and decision flowchart for choosing message types
+- Added Common Mistakes callout with troubleshooting link
+- Updated performance comparison table with accurate benchmark range (10-17M ops/sec)
+
+### Fixed
+
+- Regenerated corrupted meta files in `scripts/wiki`
+
+## [2.1.6]
+
+### Added
+
+- Concepts index page and Mental Model documentation for understanding DxMessaging's design principles
+
+### Fixed
+
+- Orphaned documentation pages in Concepts section now included in mkdocs.yml navigation
+- Burst compiler assembly resolution errors when using DxMessaging as a package on disk and building for player platforms. Benchmarks and integration test assembly definitions now specify Editor-only platform to prevent Burst from attempting to resolve these assemblies during player builds.
+
 ## [2.1.5]
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # DxMessaging for Unity
 
 <p align="center">
-  <img src="docs/images/DxMessaging-banner.svg" alt="DxMessaging Banner" width="800"/>
+  <img src="docs/images/DxMessaging-banner.svg" alt="DxMessaging - Type-safe messaging system for Unity" width="800"/>
 </p>
 
 <p align="center">
@@ -31,9 +31,11 @@ Need install instructions? Try [OpenUPM](https://openupm.com/packages/com.wallst
 ## Table of Contents
 
 - [30-Second Elevator Pitch](#30-second-elevator-pitch)
+- [Mental Model: How to Think About DxMessaging](#mental-model-how-to-think-about-dxmessaging)
 - [Quick Start (5 Minutes)](#quick-start-5-minutes)
+- [Dependency Injection (DI) Compatible](#-dependency-injection-di-compatible)
 - [Is DxMessaging Right for You?](#is-dxmessaging-right-for-you)
-- [Why DxMessaging?](#why-dxmessaging)
+- [Why DxMessaging](#why-dxmessaging)
 - [Key Features](#key-features)
 - [The DxMessaging Solution](#the-dxmessaging-solution)
 - [Real-World Examples](#real-world-examples)
@@ -65,14 +67,114 @@ Need install instructions? Try [OpenUPM](https://openupm.com/packages/com.wallst
 
 ##### Three simple message types
 
-1. **Untargeted** - "Everyone listen!" (pause game, settings changed)
-1. **Targeted** - "Tell Player to heal" (commands to specific entities)
-1. **Broadcast** - "I took damage" (things that happen to _you_ that others can observe)
+1. **Untargeted** - Global announcements
+1. **Targeted** - Commands to specific entities
+1. **Broadcast** - Observable facts from a source
+
+See [Mental Model](#mental-model-how-to-think-about-dxmessaging) for how to choose the right type.
 
 **One line:** It's a type-safe messaging system with automatic lifecycle management and built-in inspection tools.
 
 ---
 
+## Mental Model: How to Think About DxMessaging
+
+### The Core Idea
+
+DxMessaging is built around one principle: **it gets out of your way**.
+
+You have data. You need to pass it around. That's the problem. DxMessaging provides fast, simple primitives as building blocks. You model changes as message types with optional context, using game primitives (GameObjects, components) as that context.
+
+**You don't build your game INTO the messaging system.** It's opt-in and optional—a tool you reach for when it helps.
+
+### The Three Message Types: Real-World Analogies
+
+> 💡 _Diagrams below require Mermaid support. If they don't render, try viewing this file directly on [GitHub](https://github.com/wallstop/DxMessaging)._
+
+Each message type maps to a real-world communication pattern:
+
+#### 1. Untargeted = PA System 📢
+
+```mermaid
+flowchart LR
+    S[Someone] -->|announces| PA[📢 PA System]
+    PA --> L1[Listener A]
+    PA --> L2[Listener B]
+    PA --> L3[Listener C]
+```
+
+Announcements with no specific recipient. Everyone who cares can hear it.
+
+**Examples:** "The game is paused", "Settings changed", "Scene finished loading"
+
+#### 2. Targeted = Addressed Letter 📬
+
+```mermaid
+flowchart LR
+    S[Sender] -->|"To: Player"| Letter[📬 Message Bus]
+    Letter --> Player[Player receives]
+    Other1[Enemy A] -.->|ignores| Letter
+    Other2[Enemy B] -.->|ignores| Letter
+```
+
+Commands to a specific recipient. Only that entity receives them.
+
+**Examples:** "Player, heal for 10 HP", "Door #7, open", "This enemy, take 25 damage"
+
+#### 3. Broadcast = Radio Station 📻
+
+```mermaid
+flowchart LR
+    Source[Enemy] -->|"I took damage!"| Radio[📻 Message Bus]
+    Radio --> L1[Damage Numbers UI]
+    Radio --> L2[Achievement Tracker]
+    Radio --> L3[Analytics]
+    Radio --> L4[Combat Log]
+```
+
+Facts emitted by a specific source. No intended recipient—just an origin. Anyone can tune in.
+
+**Examples:** "This enemy took 25 damage", "The player picked up item X", "This chest opened"
+
+### Choosing the Right Message Type
+
+```mermaid
+flowchart TD
+    Start([I need to send a message])
+    Start --> Q1{Does it matter<br/>WHO sent it?}
+
+    Q1 -->|No| Q2{Does it matter<br/>WHO receives it?}
+    Q2 -->|No| Untargeted[Use UNTARGETED<br/>Global announcement]
+    Q2 -->|Yes| Targeted[Use TARGETED<br/>Directed command]
+
+    Q1 -->|Yes| Q3{Am I commanding<br/>someone to act?}
+    Q3 -->|Yes| Targeted
+    Q3 -->|No| Broadcast[Use BROADCAST<br/>Observable fact]
+```
+
+| Question                            | Untargeted | Targeted | Broadcast |
+| ----------------------------------- | :--------: | :------: | :-------: |
+| Has a specific sender that matters? |     ❌     |    ❌    |    ✅     |
+| Has a specific recipient?           |     ❌     |    ✅    |    ❌     |
+| Is it a command?                    |     ❌     |    ✅    |    ❌     |
+| Is it an observable fact?           |   Maybe    |    ❌    |    ✅     |
+| Is it a global announcement?        |     ✅     |    ❌    |    ❌     |
+
+> ⚠️ **Common Mistakes:**
+>
+> - **Forgetting to enable the token** — Messages won't be received. Use `MessageAwareComponent` (auto-enables) or call `Token.Enable()` manually.
+> - **Targeting Component when you meant GameObject** — These are distinct registration paths. Component-targeted messages won't reach GameObject-level handlers.
+> - **Using Broadcast when you need Targeted** — Broadcasts have no recipient, just an origin. Use Targeted when commanding a specific entity.
+> - **Missing `[Dx*Message]` attribute** — The source generator won't process the struct without the marker attribute.
+>
+> 📖 See [Troubleshooting](docs/reference/troubleshooting.md) for solutions to these and other issues.
+
+📖 **Want more depth?** See the full [Mental Model documentation](docs/concepts/mental-model.md) for detailed examples, lifecycle patterns, and edge cases.
+
+📖 **Ready to code?** Jump to [Quick Start](#quick-start-5-minutes) to send your first message!
+
+---
+
 ## Quick Start (5 Minutes)
 
 **New to messaging?** Start with the [Visual Guide](docs/getting-started/visual-guide.md) (5 min) for a beginner-friendly introduction!
@@ -85,7 +187,7 @@ Need install instructions? Try [OpenUPM](https://openupm.com/packages/com.wallst
 openupm add com.wallstop-studios.dxmessaging
 ```
 
-##### Or via Git URL
+#### Or via Git URL
 
 ```bash
 # Unity Package Manager > Add package from git URL...
@@ -231,20 +333,10 @@ flowchart TD
     Q3{Do you need observable, decoupled,<br/>lifecycle-safe messaging?}
     Q3 -->|YES| A3["✅ Use DxMessaging"]
     Q3 -->|NO| A4["❌ Keep it simple"]
-
-    style Q1 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style Q2 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style Q3 fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style A1 fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
-    style A2 fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
-    style A3 fill:#95de64,stroke:#237804,stroke-width:3px,color:#000
-    style A4 fill:#f0f0f0,stroke:#666,stroke-width:2px,color:#000
 ```
 
 **Rule of thumb:** If you're reading this README and thinking "this could address several challenges I'm facing," then DxMessaging may be a good fit. If you're thinking "this seems complicated," start with the [Visual Guide](docs/getting-started/visual-guide.md) or stick with simpler patterns.
 
-**New to messaging?** Start with the [Visual Guide](docs/getting-started/visual-guide.md) (5 min) for a beginner-friendly introduction!
-
 Looking for hard numbers? See OS-specific [Performance Benchmarks](docs/architecture/performance.md).
 
 ## Why DxMessaging
@@ -266,7 +358,7 @@ public class GameUI : MonoBehaviour {
 
 Months later: "Why is our game using 2GB of RAM after an hour?"
 
-##### Scenario 2: The Spaghetti Mess
+#### Scenario 2: The Spaghetti Mess
 
 ```csharp
 public class GameUI : MonoBehaviour {
@@ -289,7 +381,7 @@ public class GameUI : MonoBehaviour {
 
 **Your UI now depends on many systems.** Refactoring becomes more difficult.
 
-###### Scenario 3: The Debugging Black Hole
+#### Scenario 3: The Debugging Black Hole
 
 Player reports: "My health bar didn't update!"
 
@@ -326,7 +418,7 @@ public class GameUI : MessageAwareComponent {
 
 ###### Automatic lifecycle = leaks are prevented by default
 
-###### Scenario 2: No More Coupling
+##### Scenario 2: No More Coupling
 
 ```csharp
 public class GameUI : MessageAwareComponent {
@@ -344,7 +436,7 @@ public class GameUI : MessageAwareComponent {
 
 **Your UI is now independent.** Swapping systems no longer requires updating UI references.
 
-###### Scenario 3: Debugging is Built In
+##### Scenario 3: Debugging is Built In
 
 Open any `MessageAwareComponent` in the Inspector:
 
@@ -448,9 +540,6 @@ flowchart LR
     P[Producer] --> I[Interceptors<br/>validate/mutate]
     I --> H[Handlers<br/>main logic]
     H --> PP[Post-Processors<br/>analytics/logging]
-    style I fill:#ffe7ba,stroke:#d48806,stroke-width:2px,color:#000
-    style H fill:#91d5ff,stroke:#096dd9,stroke-width:2px,color:#000
-    style PP fill:#b7eb8f,stroke:#389e0d,stroke-width:2px,color:#000
 ```
 
 ### Global Observers: Listen to All Events
@@ -758,7 +847,7 @@ For OS-specific benchmark tables generated by PlayMode tests, see [Performance B
 | **Interceptors**         | ✅ Pipeline        | ❌ No              | ⚠️ Filters         | ❌ No              |
 | **Post-Processing**      | ✅ Dedicated       | ❌ No              | ⚠️ Filters         | ❌ No              |
 | **Stream Operators**     | ❌ No              | ✅ Extensive       | ❌ No              | ⚠️ With UniRx      |
-| **Performance**          | ✅ Good (14M)      | ✅ Good (18M)      | ✅ High (97M)      | ⚠️ Moderate (2.5M) |
+| **Performance**          | ✅ Good (10-17M)   | ✅ Good (18M)      | ✅ High (97M)      | ⚠️ Moderate (2.5M) |
 | **Dependencies**         | ✅ None            | ⚠️ UniTask         | ✅ None            | ⚠️ Zenject         |
 
 ### Comparison with Traditional Approaches

package/Tests/Runtime/Benchmarks/WallstopStudios.DxMessaging.Tests.Runtime.Benchmarks.asmdef

@@ -12,7 +12,7 @@
     "UniRx",
     "UniTask"
   ],
-  "includePlatforms": [],
+  "includePlatforms": ["Editor"],
   "excludePlatforms": [],
   "allowUnsafeCode": false,
   "overrideReferences": true,
@@ -35,11 +35,6 @@
       "expression": "0.0.1",
       "define": "UNIRX_PRESENT"
     },
-    {
-      "name": "com.svermeulen.extenject",
-      "expression": "0.0.1",
-      "define": "ZENJECT_PRESENT"
-    },
     {
       "name": "com.svermeulen.extenject",
       "expression": "0.0.1",

package/Tests/Runtime/Integrations/Reflex/WallstopStudios.DxMessaging.Tests.Runtime.Reflex.asmdef

@@ -9,7 +9,7 @@
     "Reflex",
     "WallstopStudios.DxMessaging.Reflex"
   ],
-  "includePlatforms": [],
+  "includePlatforms": ["Editor"],
   "excludePlatforms": [],
   "allowUnsafeCode": false,
   "overrideReferences": true,

package/Tests/Runtime/Integrations/VContainer/WallstopStudios.DxMessaging.Tests.Runtime.VContainer.asmdef

@@ -9,7 +9,7 @@
     "VContainer",
     "WallstopStudios.DxMessaging.VContainer"
   ],
-  "includePlatforms": [],
+  "includePlatforms": ["Editor"],
   "excludePlatforms": [],
   "allowUnsafeCode": false,
   "overrideReferences": true,

package/Tests/Runtime/Integrations/Zenject/WallstopStudios.DxMessaging.Tests.Runtime.Zenject.asmdef

@@ -9,7 +9,7 @@
     "Zenject",
     "WallstopStudios.DxMessaging.Zenject"
   ],
-  "includePlatforms": [],
+  "includePlatforms": ["Editor"],
   "excludePlatforms": [],
   "allowUnsafeCode": false,
   "overrideReferences": true,