com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

package/.llm/skills/testing/script-test-coverage.md

@@ -0,0 +1,259 @@
+---
+title: "Script Test Coverage Requirements"
+id: "script-test-coverage"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-28"
+updated: "2026-01-28"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "scripts/__tests__/"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "testing"
+  - "scripts"
+  - "jest"
+  - "coverage"
+  - "javascript"
+  - "powershell"
+  - "ci-cd"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of test architecture for scripts"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Test patterns only; no runtime performance impact"
+  maintainability:
+    rating: "high"
+    details: "Proper test coverage catches issues before CI"
+  testability:
+    rating: "critical"
+    details: "Defines testing standards for all project scripts"
+
+prerequisites:
+  - "Jest testing framework familiarity"
+  - "Understanding of JavaScript module testing"
+  - "Basic PowerShell knowledge for testing PS logic"
+
+dependencies:
+  packages:
+    - "jest"
+  skills:
+    - "cross-platform-compatibility"
+
+applies_to:
+  languages:
+    - "JavaScript"
+    - "PowerShell"
+  frameworks:
+    - "Jest"
+    - "Node.js"
+  versions:
+    node: ">=18.0"
+    jest: ">=29.0"
+
+aliases:
+  - "Script testing"
+  - "Test coverage for scripts"
+
+related:
+  - "cross-platform-compatibility"
+  - "comprehensive-test-coverage"
+
+status: "stable"
+---
+
+# Script Test Coverage Requirements
+
+> **One-line summary**: All scripts in `scripts/` must have corresponding test coverage in
+> `scripts/__tests__/` to catch bugs before CI.
+
+## Overview
+
+Every script in the project must have corresponding test coverage. This catches bugs before CI,
+including case sensitivity issues, regex pattern errors, and logic flaws. Tests are written in
+JavaScript using Jest, even when testing PowerShell script logic.
+
+## Solution
+
+1. **Create test files** in `scripts/__tests__/` for each script
+1. **Implement equivalent JavaScript functions** to test PowerShell logic
+1. **Verify file paths** to catch case sensitivity issues
+1. **Test edge cases** and error handling comprehensively
+1. **Use `test()` not `it()`** for all Jest test declarations
+
+## Test Location and Naming
+
+```text
+scripts/
+├── sync-banner-version.ps1      # PowerShell script
+├── fix-eol.js                   # JavaScript script
+└── __tests__/
+    ├── sync-banner-version.test.js  # Tests for PowerShell logic
+    └── fix-eol.test.js              # Tests for JavaScript logic
+```
+
+### Naming Convention
+
+- Test files must be named `<script-name>.test.js`
+- Place all test files in `scripts/__tests__/`
+- Test file names should match their source script names
+
+## What to Test
+
+For each script, test:
+
+1. **Core logic functions** - Extract testable functions and verify behavior
+1. **Input validation** - Invalid inputs, missing files, malformed data
+1. **Edge cases** - Empty files, special characters, boundary conditions
+1. **Error handling** - Graceful failures with informative messages
+1. **File path references** - Verify paths exist with correct case
+
+## Testing PowerShell Logic in JavaScript
+
+When the actual script is PowerShell, implement equivalent JavaScript functions for testing:
+
+```javascript
+/**
+ * @fileoverview Tests for sync-banner-version.ps1 logic.
+ *
+ * Since the actual script is PowerShell, we test equivalent JavaScript
+ * implementations of the core logic to ensure correctness.
+ */
+
+// SYNC: Keep pattern in sync with sync-banner-version.ps1
+const VERSION_PATTERN = /<!-- Version badge.*?-->\s*<g[^>]*>.*?<\/g>/s;
+
+function extractVersion(packageJsonContent) {
+  // Equivalent to PowerShell version extraction logic
+  const parsed = JSON.parse(packageJsonContent);
+  return parsed.version || null;
+}
+
+describe("Version Extraction", () => {
+  test("should extract valid semver version", () => {
+    const content = '{"version": "1.2.3"}';
+    expect(extractVersion(content)).toBe("1.2.3");
+  });
+
+  test("should return null for missing version", () => {
+    const content = '{"name": "test"}';
+    expect(extractVersion(content)).toBeNull();
+  });
+});
+```
+
+## File Path Testing Pattern
+
+When scripts reference files, test that paths are correct:
+
+```javascript
+const fs = require("fs");
+const path = require("path");
+
+describe("File References", () => {
+  test("banner file exists with expected case", () => {
+    // Test the exact path used in the PowerShell script
+    const bannerPath = path.join(__dirname, "../../docs/images/DxMessaging-banner.svg");
+    expect(fs.existsSync(bannerPath)).toBe(true);
+  });
+
+  test("banner filename case matches script reference", () => {
+    const imagesDir = path.join(__dirname, "../../docs/images");
+    const files = fs.readdirSync(imagesDir);
+    const bannerFile = files.find((f) => f.toLowerCase().includes("banner"));
+
+    // Verify exact case matches what scripts expect
+    expect(bannerFile).toBe("DxMessaging-banner.svg");
+  });
+});
+```
+
+## Jest Test Style Consistency
+
+### Use `test()` Not `it()`
+
+This project uses `test()` for all Jest test declarations. Do not use `it()` even though
+Jest treats them as equivalent.
+
+#### Rationale
+
+1. **Consistency** - All existing tests use `test()`
+1. **Clarity** - `test()` is more explicit about purpose
+1. **Searchability** - Single pattern makes grep/search easier
+
+#### Examples
+
+```javascript
+// CORRECT: Use test()
+describe("Version Extraction", () => {
+  test("should extract valid semver version", () => {
+    expect(extractVersion('{"version": "1.0.0"}')).toBe("1.0.0");
+  });
+
+  test("should handle pre-release versions", () => {
+    expect(extractVersion('{"version": "1.0.0-beta.1"}')).toBe("1.0.0-beta.1");
+  });
+});
+
+// WRONG: Do not use it()
+describe("Version Extraction", () => {
+  it("should extract valid semver version", () => {
+    // ...
+  });
+});
+```
+
+#### Nested Describes
+
+For nested `describe` blocks, continue using `test()`:
+
+```javascript
+describe("SVG Processing", () => {
+  describe("Version Badge", () => {
+    test("should find version badge in valid SVG", () => {
+      // ...
+    });
+
+    test("should return null when badge missing", () => {
+      // ...
+    });
+  });
+
+  describe("Error Handling", () => {
+    test("should handle empty content", () => {
+      // ...
+    });
+  });
+});
+```
+
+## Test Coverage Validation Checklist
+
+Before merging scripts:
+
+- [ ] JavaScript test file exists in `scripts/__tests__/`
+- [ ] Tests cover core logic functions
+- [ ] Tests verify file path correctness
+- [ ] Tests include edge cases and error scenarios
+- [ ] All tests use `test()` not `it()`
+- [ ] Test descriptions are clear and specific
+- [ ] `describe` blocks group related tests logically
+
+## See Also
+
+- [Cross-Platform Compatibility](../scripting/cross-platform-compatibility.md) - Case sensitivity patterns
+- [Comprehensive Test Coverage](./comprehensive-test-coverage.md) - General test coverage requirements
+- [PowerShell Best Practices](../scripting/powershell-best-practices.md) - PowerShell scripting patterns
+
+## Changelog
+
+| Version | Date       | Changes                                        |
+| ------- | ---------- | ---------------------------------------------- |
+| 1.0.0   | 2026-01-28 | Extracted from cross-platform-compatibility.md |

package/{Docs/DesignAndArchitecture.md.meta → .llm/skills/testing/script-test-coverage.md.meta}

@@ -1,5 +1,5 @@
 fileFormatVersion: 2
-guid: c1c6189fec1666c49a06a3295b430d22
+guid: 5d9a3c1e7b4f2a8c6e0d4b9f1a3c7e5d
 TextScriptImporter:
   externalObjects: {}
   userData: 

package/.llm/skills/testing/shared-test-fixtures-generic-base.md

@@ -0,0 +1,185 @@
+---
+title: "Shared Fixtures: Generic Base"
+id: "shared-test-fixtures-generic-base"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SharedTextureTestFixtures.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "fixtures"
+  - "generic"
+  - "reference-counting"
+
+complexity:
+  level: "advanced"
+  reasoning: "Uses static lifecycle hooks with a generic base pattern"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Avoids repeated fixture construction across tests"
+  maintainability:
+    rating: "medium"
+    details: "Provides a reusable base for multiple fixture types"
+  testability:
+    rating: "medium"
+    details: "Shared state must be controlled carefully"
+
+prerequisites:
+  - "Understanding of NUnit fixture lifecycle"
+
+dependencies:
+  packages: []
+  skills:
+    - "shared-test-fixtures"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Generic shared fixtures"
+
+related:
+  - "shared-test-fixtures"
+  - "shared-test-fixtures-reference-counting"
+
+status: "stable"
+---
+
+# Shared Fixtures: Generic Base
+
+> **One-line summary**: Use a generic base class to standardize shared fixture creation and teardown.
+
+## Overview
+
+When multiple shared fixtures exist, a generic base class avoids repeating reference counting logic.
+
+## Problem Statement
+
+Duplicated reference counting logic across fixtures increases the risk of bugs and inconsistent behavior.
+
+## Solution
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests
+{
+    using UnityEngine.SceneManagement;
+
+    public abstract class SharedFixtures<T> where T : SharedFixtures<T>, new()
+    {
+        private static readonly object syncLock = new object();
+        private static int refCount;
+        private static T instance;
+
+        public static T Instance
+        {
+            get
+            {
+                lock (syncLock)
+                {
+                    if (instance == null)
+                    {
+                        UnityEngine.Debug.LogWarning($"[{typeof(T).Name}] Accessing without Acquire()");
+                    }
+                    return instance;
+                }
+            }
+        }
+
+        public static void Acquire()
+        {
+            lock (syncLock)
+            {
+                if (refCount == 0)
+                {
+                    instance = new T();
+                    instance.Create();
+                }
+                refCount++;
+            }
+        }
+
+        public static void Release()
+        {
+            lock (syncLock)
+            {
+                refCount--;
+                if (refCount == 0)
+                {
+                    instance.Destroy();
+                    instance = default;
+                }
+            }
+        }
+
+        protected abstract void Create();
+        protected abstract void Destroy();
+    }
+
+    public sealed class SharedSceneFixtures : SharedFixtures<SharedSceneFixtures>
+    {
+        public Scene TestScene { get; private set; }
+
+        protected override void Create()
+        {
+            TestScene = SceneManager.CreateScene("SharedTestScene");
+        }
+
+        protected override void Destroy()
+        {
+            if (TestScene.isLoaded)
+            {
+                SceneManager.UnloadSceneAsync(TestScene);
+            }
+        }
+    }
+}
+```
+
+## Usage Example
+
+```csharp
+[TestFixture]
+public sealed class SceneTests : CommonTestBase
+{
+    [OneTimeSetUp]
+    public override void CommonOneTimeSetUp()
+    {
+        base.CommonOneTimeSetUp();
+        SharedSceneFixtures.Acquire();
+    }
+
+    [OneTimeTearDown]
+    public override IEnumerator CommonOneTimeTearDown()
+    {
+        SharedSceneFixtures.Release();
+        yield return base.CommonOneTimeTearDown();
+    }
+}
+```
+
+## See Also
+
+- [Shared Test Fixtures](shared-test-fixtures.md)
+- [Shared Fixtures: Reference Counting](shared-test-fixtures-reference-counting.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |

package/.llm/skills/testing/shared-test-fixtures-reference-counting.md

@@ -0,0 +1,252 @@
+---
+title: "Shared Fixtures: Reference Counting"
+id: "shared-test-fixtures-reference-counting"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SharedTextureTestFixtures.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "fixtures"
+  - "reference-counting"
+  - "thread-safety"
+
+complexity:
+  level: "advanced"
+  reasoning: "Requires careful lifecycle management of shared state"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Avoids repeated fixture construction"
+  maintainability:
+    rating: "medium"
+    details: "Shared lifecycle increases complexity"
+  testability:
+    rating: "medium"
+    details: "Shared state must be kept stable"
+
+prerequisites:
+  - "Understanding of NUnit fixture lifecycle"
+
+dependencies:
+  packages: []
+  skills:
+    - "shared-test-fixtures"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Reference-counted fixtures"
+
+related:
+  - "shared-test-fixtures"
+  - "shared-test-fixtures-generic-base"
+
+status: "stable"
+---
+
+# Shared Fixtures: Reference Counting
+
+> **One-line summary**: Use a static fixture with a reference count to manage shared resources across tests.
+
+## Overview
+
+Reference-counted fixtures ensure that expensive resources are created once and destroyed only after the last consumer releases them.
+
+## Problem Statement
+
+Without reference counting, shared fixtures are either leaked or destroyed while still in use.
+
+## Solution
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests
+{
+    using System.IO;
+    using UnityEngine;
+
+    public static class SharedTextureTestFixtures
+    {
+        private static readonly object syncLock = new object();
+        private static int refCount;
+
+        private static Texture2D solid300x100;
+        private static Texture2D solid1024x1024;
+        private static Texture2D transparent256x256;
+        private static string solid300x100Path;
+
+        public static string Solid300x100Path
+        {
+            get
+            {
+                EnsureAcquired();
+                return solid300x100Path;
+            }
+        }
+
+        public static Texture2D Solid300x100
+        {
+            get
+            {
+                EnsureAcquired();
+                return solid300x100;
+            }
+        }
+
+        public static Texture2D Solid1024x1024
+        {
+            get
+            {
+                EnsureAcquired();
+                return solid1024x1024;
+            }
+        }
+
+        public static Texture2D Transparent256x256
+        {
+            get
+            {
+                EnsureAcquired();
+                return transparent256x256;
+            }
+        }
+
+        public static void AcquireFixtures()
+        {
+            lock (syncLock)
+            {
+                if (refCount == 0)
+                {
+                    CreateFixtures();
+                }
+                refCount++;
+            }
+        }
+
+        public static void ReleaseFixtures()
+        {
+            lock (syncLock)
+            {
+                refCount--;
+                if (refCount == 0)
+                {
+                    DestroyFixtures();
+                }
+                else if (refCount < 0)
+                {
+                    Debug.LogError("[SharedTextureTestFixtures] ReleaseFixtures called more than AcquireFixtures!");
+                    refCount = 0;
+                }
+            }
+        }
+
+        private static void EnsureAcquired()
+        {
+            lock (syncLock)
+            {
+                if (refCount == 0)
+                {
+                    Debug.LogWarning("[SharedTextureTestFixtures] Accessing fixtures without AcquireFixtures()");
+                }
+            }
+        }
+
+        private static void CreateFixtures()
+        {
+            solid300x100 = CreateSolidTexture(300, 100, Color.white);
+            solid1024x1024 = CreateSolidTexture(1024, 1024, Color.white);
+            transparent256x256 = CreateSolidTexture(256, 256, new Color(1, 1, 1, 0));
+
+            string tempDir = Path.Combine(Application.temporaryCachePath, "TestFixtures");
+            Directory.CreateDirectory(tempDir);
+            solid300x100Path = Path.Combine(tempDir, "solid300x100.png");
+            File.WriteAllBytes(solid300x100Path, solid300x100.EncodeToPNG());
+        }
+
+        private static void DestroyFixtures()
+        {
+            if (solid300x100 != null)
+            {
+                Object.DestroyImmediate(solid300x100);
+                solid300x100 = null;
+            }
+            if (solid1024x1024 != null)
+            {
+                Object.DestroyImmediate(solid1024x1024);
+                solid1024x1024 = null;
+            }
+            if (transparent256x256 != null)
+            {
+                Object.DestroyImmediate(transparent256x256);
+                transparent256x256 = null;
+            }
+
+            if (!string.IsNullOrEmpty(solid300x100Path) && File.Exists(solid300x100Path))
+            {
+                File.Delete(solid300x100Path);
+                solid300x100Path = null;
+            }
+        }
+
+        private static Texture2D CreateSolidTexture(int width, int height, Color color)
+        {
+            Texture2D texture = new Texture2D(width, height, TextureFormat.RGBA32, false);
+            Color[] pixels = new Color[width * height];
+            for (int i = 0; i < pixels.Length; i++)
+            {
+                pixels[i] = color;
+            }
+            texture.SetPixels(pixels);
+            texture.Apply();
+            return texture;
+        }
+    }
+}
+```
+
+### Defensive Access Pattern
+
+```csharp
+public static Texture2D Solid300x100
+{
+    get
+    {
+        lock (syncLock)
+        {
+            if (refCount == 0)
+            {
+                throw new InvalidOperationException(
+                    "SharedTextureTestFixtures.AcquireFixtures() not called");
+            }
+            return solid300x100;
+        }
+    }
+}
+```
+
+## See Also
+
+- [Shared Test Fixtures](shared-test-fixtures.md)
+- [Shared Fixtures: Generic Base](shared-test-fixtures-generic-base.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |