com.wallstop-studios.dxmessaging 2.1.4 → 2.1.5

package/.llm/skills/solid/try-pattern-apis.md

@@ -0,0 +1,220 @@
+---
+title: "Try-Pattern APIs for Defensive Programming"
+id: "try-pattern-apis"
+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/Cache/Cache.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "solid"
+  - "defensive"
+  - "api-design"
+  - "error-handling"
+  - "patterns"
+
+complexity:
+  level: "basic"
+  reasoning: "Standard C# pattern, easy to understand and implement"
+
+impact:
+  performance:
+    rating: "high"
+    details: "Avoids exception overhead in expected failure cases"
+  maintainability:
+    rating: "high"
+    details: "Clear contract about failure modes"
+  testability:
+    rating: "high"
+    details: "Easy to test both success and failure paths"
+
+prerequisites:
+  - "Understanding of out parameters"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "TryGet pattern"
+  - "TryParse pattern"
+  - "Safe access pattern"
+
+related:
+  - "collection-extensions"
+  - "try-pattern-apis-variants"
+  - "try-pattern-apis-usage"
+
+status: "stable"
+---
+
+# Try-Pattern APIs for Defensive Programming
+
+> **One-line summary**: Implement `Try*` methods that return bool and use out parameters for operations that may fail, avoiding exceptions for expected failure cases.
+
+## Overview
+
+The Try-pattern provides a consistent way to handle operations that may legitimately fail:
+
+1. **Returns bool** indicating success/failure
+1. **Uses out parameter** for the result
+1. **Never throws** for expected failures
+1. **Zero allocation** on failure
+
+This is the standard .NET pattern (see `int.TryParse`, `Dictionary.TryGetValue`).
+
+## Problem Statement
+
+```csharp
+// BAD: Exceptions for expected cases
+public T Get(int index)
+{
+    if (index < 0 || index >= count)
+        throw new IndexOutOfRangeException(); // Expensive!
+    return items[index];
+}
+
+// Usage requires try-catch
+try
+{
+    var item = collection.Get(userIndex);
+}
+catch (IndexOutOfRangeException)
+{
+    // Handle missing item
+}
+
+// BAD: Null return is ambiguous
+public T GetOrNull(int index)
+{
+    if (index < 0 || index >= count)
+        return default; // What if T is int? default is 0, not "missing"
+    return items[index];
+}
+```
+
+## Solution
+
+### Core Pattern
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Core
+{
+    using System;
+    using System.Runtime.CompilerServices;
+
+    public sealed class SafeCollection<T>
+    {
+        private readonly T[] items;
+        private readonly int count;
+
+        /// <summary>
+        /// Attempts to get an item at the specified index.
+        /// </summary>
+        /// <param name="index">The index to retrieve.</param>
+        /// <param name="value">The item if found, default otherwise.</param>
+        /// <returns>True if the index is valid and the item was retrieved.</returns>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public bool TryGet(int index, out T value)
+        {
+            if ((uint)index < (uint)count) // Single comparison for both bounds
+            {
+                value = items[index];
+                return true;
+            }
+
+            value = default;
+            return false;
+        }
+
+        /// <summary>
+        /// Gets an item at the index, or returns a default value.
+        /// </summary>
+        [MethodImpl(MethodImplOptions.AggressiveInlining)]
+        public T GetOrDefault(int index, T defaultValue = default)
+        {
+            return TryGet(index, out T value) ? value : defaultValue;
+        }
+
+        /// <summary>
+        /// Gets an item at the index, throwing if invalid.
+        /// Use this only when an invalid index is a programming error.
+        /// </summary>
+        public T Get(int index)
+        {
+            if (!TryGet(index, out T value))
+            {
+                throw new ArgumentOutOfRangeException(
+                    nameof(index),
+                    index,
+                    $"Index must be between 0 and {count - 1}");
+            }
+            return value;
+        }
+    }
+}
+```
+
+## Performance Notes
+
+### Exception Cost vs. Try-Pattern
+
+| Scenario    | Try-Pattern | Exception |
+| ----------- | ----------- | --------- |
+| Success     | ~1ns        | ~1ns      |
+| Failure     | ~1ns        | ~10,000ns |
+| Stack trace | N/A         | +50,000ns |
+
+### Memory
+
+- **Try-Pattern**: Zero allocations on failure
+- **Exception**: Allocates exception object, captures stack trace
+
+## Best Practices
+
+### Do
+
+- Use Try-pattern when failure is expected/common
+- Set out parameter to default on failure
+- Provide GetOrDefault convenience method
+- Keep throwing version for programming errors
+- Use `(uint)index < (uint)count` for single-comparison bounds check
+
+### Don't
+
+- Don't use exceptions for expected failures
+- Don't return null when T could legitimately be null
+- Don't forget to initialize out parameter on all paths
+- Don't use Try-pattern for truly exceptional conditions (disk full, etc.)
+
+### When to Use Each Pattern
+
+| Scenario                     | Pattern                     |
+| ---------------------------- | --------------------------- |
+| User input parsing           | TryParse                    |
+| Cache lookup                 | TryGet                      |
+| Optional config              | TryGet / GetOrDefault       |
+| Programming error (null arg) | Throw ArgumentNullException |
+| System failure (disk full)   | Throw IOException           |
+
+## Related Patterns
+
+- [Collection Extensions](./collection-extensions.md) - Extension method design
+- [Try-Pattern API Variants](./try-pattern-apis-variants.md) - Dictionary, parse, and component styles
+- [Try-Pattern API Usage Examples](./try-pattern-apis-usage.md) - Usage and chaining

package/.llm/skills/specification.md

@@ -0,0 +1,465 @@
+# Skills Repository Specification
+
+This document defines the structure, schema, and tooling for storing code patterns (skills) extracted from repositories.
+
+---
+
+## 1. Directory Structure
+
+```text
+.llm/
+├── skills/
+│   ├── specification.md          # This file - the spec
+│   ├── index.md                  # Auto-generated index of all skills
+│   ├── templates/                # Skill templates
+│   │   └── skill-template.md
+│   │
+│   ├── performance/              # Performance optimization patterns
+│   │   ├── object-pooling.md
+│   │   ├── cache-strategies.md
+│   │   └── allocation-reduction.md
+│   │
+│   ├── testing/                  # Testing patterns and practices
+│   │   ├── unity-test-patterns.md
+│   │   ├── mock-strategies.md
+│   │   └── assertion-patterns.md
+│   │
+│   ├── solid/                    # SOLID principles implementations
+│   │   ├── dependency-injection.md
+│   │   ├── interface-segregation.md
+│   │   └── single-responsibility.md
+│   │
+│   ├── messaging/                # Messaging and event patterns
+│   │   ├── pub-sub-patterns.md
+│   │   ├── message-routing.md
+│   │   └── broadcast-strategies.md
+│   │
+│   ├── unity/                    # Unity-specific patterns
+│   │   ├── lifecycle-management.md
+│   │   ├── component-patterns.md
+│   │   └── editor-extensions.md
+│   │
+│   ├── concurrency/              # Threading and async patterns
+│   │   ├── thread-safety.md
+│   │   ├── lock-free-patterns.md
+│   │   └── async-patterns.md
+│   │
+│   ├── architecture/             # Architectural patterns
+│   │   ├── service-locator.md
+│   │   ├── factory-patterns.md
+│   │   └── repository-pattern.md
+│   │
+│   ├── error-handling/           # Error handling strategies
+│   │   ├── exception-patterns.md
+│   │   ├── result-types.md
+│   │   └── defensive-coding.md
+│   │
+│   ├── code-generation/          # Source generation patterns
+│   │   ├── roslyn-analyzers.md
+│   │   ├── source-generators.md
+│   │   └── emit-patterns.md
+│   │
+│   ├── scripting/                # Shell and script patterns
+│   │   ├── powershell-best-practices.md
+│   │   └── shell-patterns.md
+│   │
+│   └── documentation/            # Documentation and code comments
+│       └── documentation-updates.md
+```
+
+---
+
+## 2. YAML Frontmatter Schema
+
+Every skill file MUST include the following YAML frontmatter:
+
+```yaml
+---
+# Required Fields
+title: "Human-readable skill title"
+id: "unique-kebab-case-identifier"
+category: "performance|testing|solid|messaging|unity|concurrency|architecture|error-handling|code-generation|documentation|scripting"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+# Source Information
+source:
+  repository: "owner/repo-name"
+  files:
+    - path: "relative/path/to/file.cs"
+      lines: "10-50" # Optional: specific line range
+      commit: "abc123" # Optional: specific commit hash
+    - path: "another/file.cs"
+  url: "https://github.com/owner/repo" # Optional: direct URL
+
+# Classification
+tags:
+  - "primary-tag"
+  - "secondary-tag"
+  - "technology-tag"
+
+complexity:
+  level: "basic|intermediate|advanced|expert"
+  reasoning: "Brief explanation of complexity rating"
+
+# Impact Assessment
+impact:
+  performance:
+    rating: "none|low|medium|high|critical"
+    details: "Brief description of performance implications"
+  maintainability:
+    rating: "none|low|medium|high|critical"
+    details: "Brief description of maintainability implications"
+  testability:
+    rating: "none|low|medium|high|critical"
+    details: "Brief description of testability implications"
+
+# Dependencies and Prerequisites
+prerequisites:
+  - "Required knowledge or skill"
+  - "Another prerequisite"
+
+dependencies:
+  packages:
+    - "Package.Name >= 1.0.0"
+  skills:
+    - "related-skill-id"
+
+# Applicability
+applies_to:
+  languages:
+    - "C#"
+    - "JavaScript"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+    dotnet: ">=netstandard2.0"
+
+# Optional metadata
+aliases:
+  - "Alternative name 1"
+  - "Alternative name 2"
+
+related:
+  - "related-skill-id-1"
+  - "related-skill-id-2"
+
+status: "draft|review|stable|deprecated"
+---
+```
+
+### Field Definitions
+
+| Field                           | Type   | Required | Description                                                          |
+| ------------------------------- | ------ | -------- | -------------------------------------------------------------------- |
+| `title`                         | string | ✅       | Human-readable title for the skill                                   |
+| `id`                            | string | ✅       | Unique kebab-case identifier (must match filename without extension) |
+| `category`                      | enum   | ✅       | Primary category (must match parent folder name)                     |
+| `version`                       | semver | ✅       | Semantic version of this skill document                              |
+| `created`                       | date   | ✅       | ISO 8601 date when skill was first documented                        |
+| `updated`                       | date   | ✅       | ISO 8601 date when skill was last modified                           |
+| `source.repository`             | string | ✅       | Source repository in `owner/repo` format                             |
+| `source.files`                  | array  | ✅       | Array of source file references                                      |
+| `source.files[].path`           | string | ✅       | Relative path within source repository                               |
+| `source.files[].lines`          | string | ❌       | Line range in format `start-end`                                     |
+| `source.files[].commit`         | string | ❌       | Git commit SHA for version pinning                                   |
+| `source.url`                    | string | ❌       | Direct URL to repository or file                                     |
+| `tags`                          | array  | ✅       | Array of descriptive tags for discovery                              |
+| `complexity.level`              | enum   | ✅       | One of: basic, intermediate, advanced, expert                        |
+| `complexity.reasoning`          | string | ❌       | Explanation of complexity rating                                     |
+| `impact.performance.rating`     | enum   | ✅       | Performance impact rating                                            |
+| `impact.performance.details`    | string | ❌       | Performance impact explanation                                       |
+| `impact.maintainability.rating` | enum   | ✅       | Maintainability impact rating                                        |
+| `impact.testability.rating`     | enum   | ✅       | Testability impact rating                                            |
+| `prerequisites`                 | array  | ❌       | Required knowledge or skills                                         |
+| `dependencies.packages`         | array  | ❌       | Required NuGet/npm packages                                          |
+| `dependencies.skills`           | array  | ❌       | Related skill IDs that should be learned first                       |
+| `applies_to.languages`          | array  | ✅       | Programming languages this applies to                                |
+| `applies_to.frameworks`         | array  | ❌       | Frameworks this applies to                                           |
+| `applies_to.versions`           | object | ❌       | Version constraints                                                  |
+| `aliases`                       | array  | ❌       | Alternative names for search                                         |
+| `related`                       | array  | ❌       | IDs of related skills                                                |
+| `status`                        | enum   | ✅       | Document status: draft, review, stable, deprecated                   |
+
+---
+
+## 3. Markdown Body Format
+
+After the frontmatter, skills follow this structure:
+
+````markdown
+---
+[YAML Frontmatter]
+---
+
+# {title}
+
+> **One-line summary**: Brief description of what this pattern accomplishes.
+
+## Overview
+
+2-4 paragraphs explaining:
+
+- What problem this pattern solves
+- When to use it
+- Key benefits and trade-offs
+
+## Problem Statement
+
+Describe the specific problem this pattern addresses. Include:
+
+- Common symptoms of the problem
+- Why naive solutions don't work
+- Real-world scenarios where this matters
+
+## Solution
+
+### Core Concept
+
+Explain the fundamental idea behind the solution.
+
+### Implementation
+
+```csharp
+// Primary code example with detailed comments
+// This should be the canonical implementation
+```
+
+### Step-by-Step Breakdown
+
+1. **Step 1**: Explanation
+1. **Step 2**: Explanation
+1. **Step 3**: Explanation
+
+## Variations
+
+### Variation A: {Name}
+
+Brief description and code example for a common variation.
+
+```csharp
+// Variation code
+```
+
+### Variation B: {Name}
+
+Brief description and code example for another variation.
+
+## Usage Examples
+
+### Example 1: {Scenario Name}
+
+```csharp
+// Complete, runnable example
+```
+
+### Example 2: {Another Scenario}
+
+```csharp
+// Another complete example
+```
+
+## Anti-Patterns
+
+### ❌ Don't Do This
+
+```csharp
+// Example of what NOT to do
+```
+
+**Why it's wrong**: Explanation of the problems with this approach.
+
+### ❌ Another Anti-Pattern
+
+```csharp
+// Another bad example
+```
+
+## Testing Considerations
+
+- How to unit test code using this pattern
+- Mocking strategies
+- Edge cases to cover
+
+```csharp
+// Test example
+```
+
+## Performance Notes
+
+- Benchmarking results (if applicable)
+- Memory allocation characteristics
+- CPU usage patterns
+- When performance matters vs. when it doesn't
+
+## Migration Guide
+
+If replacing an existing pattern:
+
+1. Step-by-step migration instructions
+1. Common pitfalls during migration
+1. Rollback strategy
+
+## See Also
+
+- [Related Skill 1](../category/related-skill-1.md)
+- [Related Skill 2](../category/related-skill-2.md)
+- [External Resource](https://example.com)
+
+## References
+
+- Original source: [Link to source]
+- Related documentation: [Link]
+- Further reading: [Link]
+
+## Changelog
+
+| Version | Date       | Changes         |
+| ------- | ---------- | --------------- |
+| 1.0.0   | 2026-01-21 | Initial version |
+````
+
+---
+
+## 4. Example Complete Skill File
+
+See [the skill template](./templates/skill-template.md) for the template.
+
+See the example skill file: [Object Pooling](./performance/object-pooling.md)
+
+---
+
+## 5. Index Generation
+
+The index is auto-generated by scripts:
+
+```bash
+node scripts/generate-skills-index.js
+```
+
+To validate the index without modifying files:
+
+```bash
+node scripts/generate-skills-index.js --check
+```
+
+The generator formats the index via Prettier and normalizes CRLF/no-BOM output.
+
+### Line Endings
+
+All `.llm/` markdown files (including `index.md`) must use CRLF and no UTF-8 BOM.
+If you generate or edit skills on non-Windows environments, normalize line endings:
+
+```bash
+node scripts/fix-eol.js .llm/skills/index.md
+```
+
+### Index Format
+
+The generated `index.md` contains:
+
+- Table of contents by category
+- Full skill listing with metadata
+- Tag cloud for discovery
+- Statistics summary
+
+---
+
+## 6. Git Hooks
+
+Install the pre-commit hook to auto-regenerate the index:
+
+```bash
+# From repository root
+cp scripts/hooks/pre-commit .git/hooks/pre-commit
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+## 7. Validation
+
+Skills are validated for:
+
+1. Required frontmatter fields present
+1. `id` matches filename
+1. `category` matches parent folder
+1. All referenced files exist (when source is local)
+1. All `dependencies.skills` reference valid skill IDs
+1. Proper markdown structure
+1. **File size limits** (see below)
+
+Run validation:
+
+```bash
+node scripts/validate-skills.js
+```
+
+---
+
+## 8. File Size Requirements
+
+All skill files and `context.md` must adhere to line count limits:
+
+| Range         | Status       | Action                                     |
+| ------------- | ------------ | ------------------------------------------ |
+| < 200 lines   | 📝 Short     | Consider adding more examples or detail    |
+| 200-350 lines | ✅ **Ideal** | Target range for all skill files           |
+| 351-500 lines | ⚠️ Warning   | Consider splitting into focused sub-skills |
+| > 500 lines   | ❌ **Error** | Must split; blocks CI and pre-commit       |
+
+### Why These Limits?
+
+- **LLM context efficiency**: Smaller, focused files fit better in context windows
+- **Maintainability**: Easier to review, update, and keep accurate
+- **Discoverability**: Focused topics are easier to find and reference
+- **Cognitive load**: Both humans and LLMs handle focused content better
+
+### When to Split
+
+Split a skill file when:
+
+1. Line count exceeds 350 lines
+1. Multiple distinct variations could stand alone
+1. Different complexity levels (basic vs. advanced)
+1. Different platform targets (Unity vs. general .NET)
+
+### How to Split
+
+1. Identify the core concept and each major variation
+1. Create separate files: `{concept}.md`, `{concept}-{variation}.md`
+1. Use `related` frontmatter to link related skills
+1. Add `## See Also` sections for cross-references
+
+See the [Skill File Sizing skill](./documentation/skill-file-sizing.md) for detailed guidance.
+
+---
+
+## 9. Contributing New Skills
+
+1. Copy `templates/skill-template.md` to the appropriate category folder
+1. Rename to `{skill-id}.md` (kebab-case)
+1. Fill in all required frontmatter fields
+1. Write the skill content following the body format
+1. Run validation
+1. Commit (index auto-regenerates via hook)
+
+---
+
+## Category Definitions
+
+| Category          | Description                            | Example Skills                                |
+| ----------------- | -------------------------------------- | --------------------------------------------- |
+| `performance`     | Optimization patterns for speed/memory | Object pooling, caching, allocation reduction |
+| `testing`         | Testing strategies and patterns        | Mocking, assertions, test organization        |
+| `solid`           | SOLID principle implementations        | DI, ISP, SRP patterns                         |
+| `messaging`       | Event and messaging patterns           | Pub/sub, routing, broadcasting                |
+| `unity`           | Unity-specific patterns                | Lifecycle, components, editor tools           |
+| `concurrency`     | Threading and async patterns           | Thread safety, locks, async/await             |
+| `architecture`    | Structural design patterns             | Factories, repositories, services             |
+| `error-handling`  | Error and exception patterns           | Result types, defensive coding                |
+| `code-generation` | Metaprogramming patterns               | Roslyn, source generators                     |
+| `documentation`   | Documentation patterns and maintenance | Changelog management, API docs, code comments |