com.wallstop-studios.dxmessaging 2.1.4 → 2.1.6

package/.llm/skills/scripting/validation-patterns.md

@@ -0,0 +1,418 @@
+---
+title: "Validation Patterns and Duplicate Warning Prevention"
+id: "validation-patterns"
+category: "scripting"
+version: "1.1.0"
+created: "2026-01-30"
+updated: "2026-01-30"
+
+source:
+  repository: "wallstop/DxMessaging"
+  files:
+    - path: "scripts/validate-skills.js"
+    - path: "scripts/__tests__/validate-skills-optional-fields.test.js"
+  url: "https://github.com/wallstop/DxMessaging"
+
+tags:
+  - "validation"
+  - "javascript"
+  - "error-handling"
+  - "duplicate-warnings"
+  - "enum-validation"
+  - "optional-fields"
+  - "testing"
+  - "truthiness"
+  - "type-coercion"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of validation flow, conditional logic ordering, and JavaScript type coercion"
+
+impact:
+  performance:
+    rating: "none"
+    details: "Validation patterns only; no runtime performance impact"
+  maintainability:
+    rating: "high"
+    details: "Prevents confusing duplicate warnings that obscure actual issues"
+  testability:
+    rating: "high"
+    details: "Clear validation logic is easier to test exhaustively"
+
+prerequisites:
+  - "JavaScript fundamentals"
+  - "Understanding of null/undefined distinction"
+  - "Basic validation concepts"
+
+dependencies:
+  skills:
+    - "javascript-code-quality"
+
+applies_to:
+  languages:
+    - "JavaScript"
+    - "TypeScript"
+  frameworks:
+    - "Node.js"
+
+aliases:
+  - "duplicate warning prevention"
+  - "validation deduplication"
+  - "enum validation"
+  - "presence vs truthiness"
+
+related:
+  - "javascript-code-quality"
+  - "comprehensive-test-coverage"
+
+status: "stable"
+---
+
+# Validation Patterns and Duplicate Warning Prevention
+
+> **One-line summary**: Structure validation logic to produce exactly one warning per issue,
+> not duplicates from multiple overlapping checks.
+
+## Overview
+
+When validating fields that have multiple possible error conditions (missing, empty, invalid enum
+value), careless ordering can produce duplicate warnings for the same underlying issue. This
+confuses users and makes debugging harder.
+
+## Solution
+
+1. **Order validation checks from most specific to most general** - check for missing/empty before
+   checking for invalid values
+1. **Use else-if chains** to ensure only one warning per field
+1. **Exclude empty/null values from enum validation** - an empty string is "empty," not "invalid enum"
+1. **Write integration tests** that verify exactly one warning per field condition
+1. **Use explicit presence checks** - avoid truthiness-based validation that conflates different issues
+
+## Truthiness vs Presence Checks
+
+### The Anti-Pattern: Using Truthiness for Presence
+
+Truthiness-based checks (`!value`, `if (value)`) conflate multiple distinct conditions, producing
+misleading error messages and duplicate warnings.
+
+```javascript
+// WRONG: Truthiness-based validation
+function validateField(frontmatter, field) {
+  if (!frontmatter[field]) {
+    // This triggers for:
+    // - undefined (missing)
+    // - null (missing)
+    // - "" (empty string - should be separate error)
+    // - 0 (legitimate value for numeric fields!)
+    // - false (legitimate value for boolean fields!)
+    errors.push(`Required field '${field}' is missing`);
+  }
+}
+```
+
+### The Correct Pattern: Explicit Presence Checks
+
+Use explicit null/undefined checks, then separate empty string checks:
+
+```javascript
+// RIGHT: Presence-based validation with explicit checks
+function validateField(frontmatter, field) {
+  if (frontmatter[field] === undefined || frontmatter[field] === null) {
+    errors.push(`Required field '${field}' is missing`);
+  } else if (frontmatter[field] === "") {
+    errors.push(`Required field '${field}' is empty`);
+  }
+}
+
+// ALSO RIGHT: Using loose equality shorthand (null == undefined is true)
+function validateField(frontmatter, field) {
+  if (frontmatter[field] == null) {
+    errors.push(`Required field '${field}' is missing`);
+  } else if (frontmatter[field] === "") {
+    errors.push(`Required field '${field}' is empty`);
+  }
+}
+```
+
+### The Guard Clause Pattern: `!= null && !== ''`
+
+When validating a value (checking if it's in an enum, matches a regex, etc.), guard against
+both missing and empty values to prevent spurious "invalid value" errors:
+
+```javascript
+// RIGHT: Guard against missing and empty before validating
+if (value != null && value !== "" && !VALID_VALUES.includes(value)) {
+  errors.push(`Invalid ${fieldName}: '${value}'`);
+}
+
+// WRONG: Missing guard allows empty string to be flagged as "invalid"
+if (!VALID_VALUES.includes(value)) {
+  // Empty string "" will produce: "Invalid fieldName: ''"
+  // Should be "fieldName is empty" instead!
+  errors.push(`Invalid ${fieldName}: '${value}'`);
+}
+```
+
+## Type Coercion Considerations
+
+### When to Use `String()`
+
+YAML parsers may return non-string types for values that look like numbers or dates:
+
+```yaml
+version: 1.0.0 # Parsed as number 1 (decimal truncated!)
+created: 2026-01-30 # Parsed as Date object in some parsers
+```
+
+Use `String()` to safely coerce before string operations:
+
+```javascript
+// RIGHT: Coerce before regex matching
+if (frontmatter.version != null && frontmatter.version !== "") {
+  const versionStr = String(frontmatter.version);
+  if (!versionStr.match(/^\d+\.\d+\.\d+$/)) {
+    warnings.push(`Version '${versionStr}' should be semver format`);
+  }
+}
+
+// WRONG: Assumes string type
+if (frontmatter.version != null && frontmatter.version !== "") {
+  if (!frontmatter.version.match(/^\d+\.\d+\.\d+$/)) {
+    // TypeError if version is a number!
+    warnings.push(`Invalid version format`);
+  }
+}
+```
+
+### Edge Cases with Type Coercion
+
+| Input Value | `String(value)` Result | Notes                         |
+| ----------- | ---------------------- | ----------------------------- |
+| `1.0`       | `"1"`                  | Decimal .0 is lost!           |
+| `null`      | `"null"`               | Check before coercing         |
+| `undefined` | `"undefined"`          | Check before coercing         |
+| `[1, 2]`    | `"1,2"`                | Array becomes comma-separated |
+| `{a: 1}`    | `"[object Object]"`    | Objects need special handling |
+| `true`      | `"true"`               | Boolean to string             |
+| `0`         | `"0"`                  | Zero is preserved             |
+
+**Best Practice**: Always check for `null`/empty before coercing:
+
+```javascript
+if (value != null && value !== "") {
+  const strValue = String(value);
+  // Now safe to validate strValue
+}
+```
+
+## The Duplicate Warning Problem
+
+### Anti-Pattern: Overlapping Validation Checks
+
+```javascript
+// BAD: Two separate if statements can both trigger for the same issue
+function validateField(value, fieldName) {
+  const warnings = [];
+
+  // Check 1: Is the value invalid according to enum?
+  if (!VALID_VALUES.includes(value)) {
+    warnings.push(`Invalid ${fieldName}: '${value}'`);
+  }
+
+  // Check 2: Is the value missing or empty?
+  if (value == null || value === "") {
+    warnings.push(`Missing ${fieldName}`);
+  }
+
+  return warnings;
+}
+
+// When called with empty string:
+validateField("", "complexity.level");
+// Returns TWO warnings:
+// - "Invalid complexity.level: ''"  (because '' is not in VALID_VALUES)
+// - "Missing complexity.level"       (because '' === "")
+```
+
+### Correct Pattern: Mutually Exclusive Checks
+
+```javascript
+// GOOD: Ordered checks ensure exactly one warning
+function validateField(value, fieldName) {
+  const warnings = [];
+
+  // Check 1: Is the value missing?
+  if (value == null) {
+    warnings.push(`Missing ${fieldName}`);
+  }
+  // Check 2: Is the value empty string?
+  else if (value === "") {
+    warnings.push(`Empty ${fieldName}`);
+  }
+  // Check 3: Is the value invalid? (Only check if value is present and non-empty)
+  else if (!VALID_VALUES.includes(value)) {
+    warnings.push(`Invalid ${fieldName}: '${value}'`);
+  }
+
+  return warnings;
+}
+
+// When called with empty string:
+validateField("", "complexity.level");
+// Returns exactly ONE warning:
+// - "Empty complexity.level"
+```
+
+## Real-World Example: Skill File Validation
+
+This pattern is implemented in [validate-skills.js](../../scripts/validate-skills.js):
+
+```javascript
+// Validate complexity level - exclude empty values from enum check
+if (
+  frontmatter.complexity != null &&
+  frontmatter.complexity.level != null &&
+  frontmatter.complexity.level !== "" && // <-- Key: exclude empty strings
+  !VALID_COMPLEXITY_LEVELS.includes(frontmatter.complexity.level)
+) {
+  warnings.push(
+    new ValidationError(
+      skillFile.relativePath,
+      "complexity.level",
+      `Invalid complexity level '${frontmatter.complexity.level}'. Valid: ${VALID_COMPLEXITY_LEVELS.join(", ")}`
+    )
+  );
+}
+
+// Later, check for missing/empty (mutually exclusive with above)
+if (frontmatter.complexity == null || frontmatter.complexity.level == null) {
+  warnings.push(
+    new ValidationError(
+      skillFile.relativePath,
+      "complexity.level",
+      `Missing 'complexity.level' - will show '?' in Complexity column of skills index`
+    )
+  );
+} else if (frontmatter.complexity.level === "") {
+  warnings.push(
+    new ValidationError(
+      skillFile.relativePath,
+      "complexity.level",
+      `Empty 'complexity.level' - will show '?' in Complexity column of skills index`
+    )
+  );
+}
+```
+
+## Integration Testing for Warning Counts
+
+Always write integration tests that verify the exact number of warnings produced:
+
+```javascript
+// GOOD: Integration test that verifies no duplicate warnings
+describe("empty string complexity.level produces exactly one warning", () => {
+  test("should produce exactly 1 warning (no duplicate from invalid enum check)", () => {
+    const content = createValidFrontmatter({
+      complexity: { level: "" }
+    });
+    const skillFile = createMockSkillFile(tempDir, content);
+
+    const result = validateSkill(skillFile);
+
+    // Filter warnings for the specific field
+    const complexityWarnings = result.warnings.filter((w) => w.field === "complexity.level");
+
+    // Key assertion: exactly ONE warning, not two
+    expect(complexityWarnings).toHaveLength(1);
+    expect(complexityWarnings[0].message).toContain("Empty 'complexity.level'");
+  });
+});
+```
+
+## Validation Check Ordering Rules
+
+1. **Null/undefined first** - the most fundamental check (is the value present?)
+1. **Empty string second** - present but semantically empty
+1. **Type checks third** - is it the right type (array, object, string)?
+1. **Format/enum checks last** - only check value validity if value is present and correct type
+
+```javascript
+// Optimal ordering for comprehensive validation
+function validateOptionalField(value, fieldName, validValues) {
+  // 1. Missing check
+  if (value == null) {
+    return [{ type: "warning", message: `Missing ${fieldName}` }];
+  }
+
+  // 2. Empty string check
+  if (value === "") {
+    return [{ type: "warning", message: `Empty ${fieldName}` }];
+  }
+
+  // 3. Type check (if applicable)
+  if (typeof value !== "string") {
+    return [{ type: "warning", message: `${fieldName} must be a string` }];
+  }
+
+  // 4. Enum/format check (only reached if all above pass)
+  if (!validValues.includes(value)) {
+    return [{ type: "warning", message: `Invalid ${fieldName}: '${value}'` }];
+  }
+
+  return []; // Valid
+}
+```
+
+## Common Mistakes Checklist
+
+Before committing validation code, verify:
+
+- [ ] Empty strings don't trigger both "invalid enum" and "empty field" warnings
+- [ ] Null/undefined values don't trigger both "invalid enum" and "missing field" warnings
+- [ ] Integration tests verify exactly one warning per field per condition
+- [ ] Validation checks use else-if chains or early returns to ensure mutual exclusivity
+- [ ] Filter by field name when counting warnings in tests (to isolate the field under test)
+
+## Troubleshooting
+
+### Duplicate Warnings Appearing in Output
+
+**Symptom**: A field produces two similar warnings (e.g., both "Missing X" and "Invalid X: ''")
+
+**Diagnosis**:
+
+1. Check if the enum validation excludes empty/null values with explicit checks
+1. Verify else-if chains are used instead of separate if statements
+1. Run integration tests that filter by field name and verify warning count
+
+**Solution**: Ensure enum validation includes `value !== ''` in its guard clause:
+
+```javascript
+// Add empty string exclusion to enum check
+if (value != null && value !== "" && !VALID_VALUES.includes(value)) {
+  // Only one warning path
+}
+```
+
+### Whitespace-Only Strings Triggering Wrong Warning
+
+**Symptom**: Input like `"   "` produces "Invalid enum" instead of "Empty field"
+
+**Explanation**: Current validation does not trim whitespace, so `"   "` is treated as a
+non-empty string that fails enum validation. This is intentional - if whitespace-only should
+be treated as empty, add explicit `.trim()` checks.
+
+### Test Counting More Warnings Than Expected
+
+**Symptom**: Test expects 1 warning but gets 2+
+
+**Diagnosis**:
+
+1. Filter warnings by field name: `result.warnings.filter(w => w.field === "fieldName")`
+1. Log all warnings to see what's being produced
+1. Check if both enum validation and missing/empty checks are triggering
+
+## See Also
+
+- [JavaScript Code Quality](javascript-code-quality.md) - General JavaScript best practices
+- [Comprehensive Test Coverage](../testing/comprehensive-test-coverage.md) - Test coverage requirements

package/.llm/skills/solid/collection-extensions-accessors.md

@@ -0,0 +1,229 @@
+---
+title: "Collection Extensions: Accessors"
+id: "collection-extensions-accessors"
+category: "solid"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Runtime/Core/Extension/IReadonlyListExtensions.cs"
+    - path: "Runtime/Core/Extension/CollectionExtensions.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "collections"
+  - "extensions"
+  - "try-pattern"
+  - "performance"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of extension method design and null safety"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Avoids allocations by using direct index access"
+  maintainability:
+    rating: "high"
+    details: "Consistent access patterns across collection types"
+  testability:
+    rating: "high"
+    details: "Pure functions are easy to test"
+
+prerequisites:
+  - "Understanding of extension methods"
+  - "Knowledge of collection interfaces"
+
+dependencies:
+  packages: []
+  skills:
+    - "collection-extensions"
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+
+aliases:
+  - "TryGet extensions"
+
+related:
+  - "collection-extensions"
+  - "try-pattern-apis"
+  - "collection-extensions-type-specialization"
+
+status: "stable"
+---
+
+# Collection Extensions: Accessors
+
+> **One-line summary**: Provide Try-pattern accessors and null-safe checks for common collection types.
+
+## Overview
+
+Accessor helpers make collections safer to use while avoiding allocations from LINQ. They should be documented with complexity and allocation notes.
+
+## Problem Statement
+
+Many access patterns either throw on empty collections or allocate enumerators. Try-pattern accessors avoid both issues.
+
+## Solution
+
+### Core Concept
+
+Provide small, inlinable helpers for first/last/random access and null/empty checks.
+
+### Implementation
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core.Extensions
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Runtime.CompilerServices;
+
+    public static class IReadOnlyListExtensions
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool TryGetFirst<T>(this IReadOnlyList<T> list, out T value)
+        {
+            if (list == null)
+            {
+                throw new ArgumentNullException(nameof(list));
+            }
+
+            if (list.Count > 0)
+            {
+                value = list[0];
+                return true;
+            }
+
+            value = default;
+            return false;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool TryGetLast<T>(this IReadOnlyList<T> list, out T value)
+        {
+            if (list == null)
+            {
+                throw new ArgumentNullException(nameof(list));
+            }
+
+            int count = list.Count;
+            if (count > 0)
+            {
+                value = list[count - 1];
+                return true;
+            }
+
+            value = default;
+            return false;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static T GetRandom<T>(this IReadOnlyList<T> list)
+        {
+            if (list == null)
+            {
+                throw new ArgumentNullException(nameof(list));
+            }
+
+            if (list.Count == 0)
+            {
+                throw new InvalidOperationException("Cannot get random element from empty list.");
+            }
+
+            return list[UnityEngine.Random.Range(0, list.Count)];
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool TryGetRandom<T>(this IReadOnlyList<T> list, out T value)
+        {
+            if (list == null)
+            {
+                throw new ArgumentNullException(nameof(list));
+            }
+
+            if (list.Count > 0)
+            {
+                value = list[UnityEngine.Random.Range(0, list.Count)];
+                return true;
+            }
+
+            value = default;
+            return false;
+        }
+    }
+
+    public static class CollectionExtensions
+    {
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool IsNullOrEmpty<T>(this IReadOnlyCollection<T> collection)
+        {
+            return collection == null || collection.Count == 0;
+        }
+
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public static bool IsNullOrEmpty<T>(this T[] array)
+        {
+            return array == null || array.Length == 0;
+        }
+
+        public static bool IsNullOrEmpty<T>(this IEnumerable<T> enumerable)
+        {
+            if (enumerable == null)
+            {
+                return true;
+            }
+
+            if (enumerable is ICollection<T> collection)
+            {
+                return collection.Count == 0;
+            }
+
+            if (enumerable is IReadOnlyCollection<T> readOnlyCollection)
+            {
+                return readOnlyCollection.Count == 0;
+            }
+
+            using (IEnumerator<T> enumerator = enumerable.GetEnumerator())
+            {
+                return !enumerator.MoveNext();
+            }
+        }
+    }
+}
+```
+
+## Usage Examples
+
+```csharp
+if (enemies.TryGetFirst(out Enemy first))
+{
+    first.Attack();
+}
+
+if (items.IsNullOrEmpty())
+{
+    Debug.Log("No items");
+}
+```
+
+## See Also
+
+- [Collection Extension Methods](collection-extensions.md)
+- [Try-Pattern APIs](./try-pattern-apis.md)
+- [Collection Extensions: Type Specialization](collection-extensions-type-specialization.md)
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |