com.wallstop-studios.dxmessaging 2.1.3 → 2.1.5

package/.llm/skills/testing/data-driven-tests.md

@@ -0,0 +1,197 @@
+---
+title: "Data-Driven Tests with TestCaseSource"
+id: "data-driven-tests"
+category: "testing"
+version: "1.0.0"
+created: "2026-01-21"
+updated: "2026-01-21"
+
+source:
+  repository: "wallstop/unity-helpers"
+  files:
+    - path: "Tests/Runtime/SpriteSettingsTests.cs"
+    - path: "Tests/Runtime/ParabolaTests.cs"
+  url: "https://github.com/wallstop/unity-helpers"
+
+tags:
+  - "testing"
+  - "parameterized"
+  - "data-driven"
+  - "nunit"
+  - "test-cases"
+
+complexity:
+  level: "intermediate"
+  reasoning: "Requires understanding of NUnit's parameterized test features"
+
+impact:
+  performance:
+    rating: "low"
+    details: "No runtime impact; test execution time unchanged"
+  maintainability:
+    rating: "high"
+    details: "Reduces test duplication significantly"
+  testability:
+    rating: "high"
+    details: "Easy to add new test cases"
+
+prerequisites:
+  - "Understanding of NUnit attributes"
+
+dependencies:
+  packages: []
+  skills: []
+
+applies_to:
+  languages:
+    - "C#"
+  frameworks:
+    - "Unity"
+    - ".NET"
+  versions:
+    unity: ">=2021.3"
+
+aliases:
+  - "Parameterized tests"
+  - "TestCaseSource"
+  - "TestCase attribute"
+
+related:
+  - "test-categories"
+  - "test-diagnostics"
+  - "data-driven-tests-sources"
+  - "data-driven-tests-usage"
+
+status: "stable"
+---
+
+# Data-Driven Tests with TestCaseSource
+
+> **One-line summary**: Use NUnit's `[TestCase]` and `[TestCaseSource]` attributes to run the same test logic with multiple inputs, reducing duplication and improving coverage.
+
+## Overview
+
+Data-driven testing separates test logic from test data:
+
+1. **Test method** defines what to test
+1. **Test cases** define the inputs and expected outputs
+
+This pattern eliminates copy-paste tests and makes adding new cases trivial.
+
+## Problem Statement
+
+```csharp
+// BAD: Duplicated test methods
+[Test]
+public void ParseIntegerZero()
+{
+    Assert.AreEqual(0, Parser.ParseInt("0"));
+}
+
+[Test]
+public void ParseIntegerPositive()
+{
+    Assert.AreEqual(42, Parser.ParseInt("42"));
+}
+
+[Test]
+public void ParseIntegerNegative()
+{
+    Assert.AreEqual(-5, Parser.ParseInt("-5"));
+}
+
+[Test]
+public void ParseIntegerWithSpaces()
+{
+    Assert.AreEqual(7, Parser.ParseInt("  7  "));
+}
+
+// 4 methods doing the same thing with different data!
+```
+
+## Solution
+
+### Using TestCase Attribute
+
+```csharp
+namespace WallstopStudios.UnityHelpers.Tests
+{
+    using NUnit.Framework;
+
+    [TestFixture]
+    public sealed class ParserTests
+    {
+        [Test]
+        [TestCase("0", 0)]
+        [TestCase("42", 42)]
+        [TestCase("-5", -5)]
+        [TestCase("  7  ", 7)]
+        [TestCase("999999", 999999)]
+        [TestCase("-999999", -999999)]
+        public void ParseIntegerHandlesValidInput(string input, int expected)
+        {
+            int result = Parser.ParseInt(input);
+            Assert.AreEqual(
+                expected,
+                result,
+                $"Input '{input}' should parse to {expected}, got {result}");
+        }
+
+        [Test]
+        [TestCase("")]
+        [TestCase("abc")]
+        [TestCase("12.34")]
+        [TestCase(null)]
+        public void ParseIntegerThrowsOnInvalidInput(string input)
+        {
+            Assert.Throws<FormatException>(
+                () => Parser.ParseInt(input),
+                $"Input '{input ?? "null"}' should throw FormatException");
+        }
+    }
+}
+```
+
+## Performance Notes
+
+- **Test Discovery**: Slight overhead for TestCaseSource reflection
+- **Execution**: Same as regular tests
+- **Memory**: Test cases are created once per test run
+
+## Best Practices
+
+### Do
+
+- Use `[TestCase]` for simple, inline cases (2-5 cases)
+- Use `[TestCaseSource]` for many cases or complex data
+- Include descriptive failure messages with all parameters
+- Use `SetName()` for human-readable test names
+- Group related test cases in named methods
+
+### Don't
+
+- Don't duplicate test logic across test methods
+- Don't forget to test edge cases (null, empty, bounds)
+- Don't use TestCaseSource for single test cases (overhead)
+- Don't make test case generation overly complex
+
+### Organizing Test Cases
+
+```csharp
+// Group by category
+private static IEnumerable<TestCaseData> HappyPathCases() { }
+private static IEnumerable<TestCaseData> EdgeCases() { }
+private static IEnumerable<TestCaseData> ErrorCases() { }
+
+// Or by feature
+private static IEnumerable<TestCaseData> ParsingCases() { }
+private static IEnumerable<TestCaseData> FormattingCases() { }
+private static IEnumerable<TestCaseData> ValidationCases() { }
+```
+
+## Related Patterns
+
+- [Test Categories](./test-categories.md) - Organizing tests
+- [Expressive Assertions](./expressive-assertions.md) - Clear failure messages
+- [Data-Driven Test Sources](./data-driven-tests-sources.md) - Advanced TestCaseSource patterns
+- [Data-Driven Test Usage Patterns](./data-driven-tests-usage.md) - Naming and diagnostics

package/.llm/skills/testing/git-workflow-robustness.md

@@ -0,0 +1,369 @@
+---
+id: git-workflow-robustness
+title: "Git and Parser Robustness in CI/CD"
+description: "Best practices for robust git commands and markdown parsing in workflows"
+version: 1.0.0
+created: 2026-01-27
+updated: 2026-01-27
+status: stable
+category: testing
+
+tags:
+  - testing
+  - git
+  - ci-cd
+  - workflows
+  - markdown
+  - parsing
+
+complexity:
+  level: intermediate
+  prerequisites:
+    - Basic shell scripting
+    - Git fundamentals
+    - Markdown syntax
+
+impact:
+  performance:
+    rating: "none"
+    details: "CI/CD patterns only; no runtime impact"
+  testability:
+    rating: high
+    description: Prevents flaky tests from git edge cases
+  maintainability:
+    rating: medium
+    description: Improves parser reliability
+
+related:
+  - testing/comprehensive-test-coverage
+  - documentation/documentation-updates
+---
+
+# Git and Parser Robustness in CI/CD
+
+## Overview
+
+This skill covers best practices for writing robust git commands in CI/CD pipelines and
+implementing reliable markdown parsers that handle edge cases correctly.
+
+## Solution
+
+## Git Command Edge Cases
+
+### Initial Commits and Single-Commit Repositories
+
+Git commands that reference previous commits can fail in specific repository states:
+
+```bash
+# DANGEROUS: Fails on initial commit (no HEAD~1 exists)
+git diff HEAD~1 -- path/to/file
+
+# DANGEROUS: Fails on single-commit repos
+git log --oneline -2  # May return fewer than 2 commits
+```
+
+#### Solution patterns
+
+```bash
+# Check commit count before referencing ancestors
+COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo "0")
+if [ "$COMMIT_COUNT" -gt 1 ]; then
+    git diff HEAD~1 -- path/to/file
+else
+    echo "No previous commit to compare against"
+fi
+```
+
+```bash
+# Use --first-parent and handle errors gracefully
+git diff HEAD~1 -- path/to/file 2>/dev/null || true
+```
+
+### Shallow Clones in CI Environments
+
+Many CI systems use shallow clones for speed. Commands that traverse history may fail:
+
+```bash
+# DANGEROUS: May fail with shallow clone
+git log --oneline --all
+
+# DANGEROUS: Ancestor references may not exist
+git merge-base main feature-branch
+```
+
+#### Solution patterns
+
+```bash
+# Fetch sufficient depth before operations
+git fetch --depth=50 origin main
+
+# Or unshallow if needed
+git fetch --unshallow 2>/dev/null || true
+```
+
+### Detached HEAD States
+
+CI systems often check out specific commits, creating detached HEAD states:
+
+```bash
+# DANGEROUS: Branch name queries fail in detached HEAD
+git branch --show-current  # Returns empty string
+
+# DANGEROUS: Assumes branch context
+git push origin HEAD:refs/heads/$(git branch --show-current)
+```
+
+#### Solution patterns
+
+```bash
+# Check for detached HEAD before branch operations
+CURRENT_BRANCH=$(git branch --show-current)
+if [ -z "$CURRENT_BRANCH" ]; then
+    echo "In detached HEAD state, using SHA instead"
+    CURRENT_REF=$(git rev-parse HEAD)
+else
+    CURRENT_REF=$CURRENT_BRANCH
+fi
+```
+
+### Empty Repository States
+
+Scripts must handle repositories with no commits:
+
+```bash
+# DANGEROUS: Fails on empty repos
+git log --oneline -1
+
+# DANGEROUS: HEAD doesn't exist
+git rev-parse HEAD
+```
+
+#### Solution patterns
+
+```bash
+# Check if HEAD exists before using it
+if git rev-parse HEAD >/dev/null 2>&1; then
+    git log --oneline -1
+else
+    echo "Repository has no commits"
+fi
+```
+
+### File Path Edge Cases
+
+Git commands with file paths can fail unexpectedly:
+
+```bash
+# DANGEROUS: Fails if path contains spaces
+git diff HEAD -- $FILE_PATH
+
+# DANGEROUS: Glob patterns may match nothing
+git diff HEAD -- *.md
+```
+
+#### Solution patterns
+
+```bash
+# Always quote variables containing paths
+git diff HEAD -- "$FILE_PATH"
+
+# Use nullglob or check pattern expansion
+shopt -s nullglob
+FILES=(*.md)
+if [ ${#FILES[@]} -gt 0 ]; then
+    git diff HEAD -- "${FILES[@]}"
+fi
+```
+
+### Line Ending Normalization: Index vs Working Tree
+
+`git add --renormalize` is commonly misunderstood. It updates the git **index** (staging area) based on `.gitattributes` rules but does **not** modify working tree files:
+
+```bash
+# MISLEADING: This does NOT fix files on disk
+git add --renormalize -- '*.md' '**/*.md'
+# After this command:
+# - Index: updated with normalized content
+# - Working tree: UNCHANGED (still has original line endings)
+# - Repository: left in a staged state
+```
+
+#### When to use each approach
+
+| Goal                                         | Command                           |
+| -------------------------------------------- | --------------------------------- |
+| Fix files on disk after cloning              | `node scripts/fix-eol.js`         |
+| Re-stage files after `.gitattributes` change | `git add --renormalize`           |
+| Fix files copied from external source        | `node scripts/fix-eol.js`         |
+| Verify line endings without changing         | `node scripts/check-eol.js`       |
+| Verify line endings before committing        | `node scripts/check-eol.js --all` |
+
+#### Working tree fix pattern
+
+```bash
+# Recommended: Fix working tree directly
+node scripts/fix-eol.js
+
+# Optional: Verbose mode shows what was fixed
+node scripts/fix-eol.js -v
+```
+
+## Markdown Inline Code Parsing
+
+### CommonMark Multi-Backtick Semantics
+
+CommonMark defines specific rules for code spans with multiple backticks:
+
+1. Opening and closing sequences must have the **same number of backticks**
+1. Content can contain backticks with fewer characters than the delimiter
+1. A single backtick inside double-backtick delimiters is literal text
+
+#### Examples
+
+````markdown
+`code` → <code>code</code>
+`code` → <code>code</code>
+`` `code` `` → <code>`code`</code>
+```a`b`` → <code>a`b</code> (opened with ``, closed with ``)
+`` a ` b ``     → <code>a` b</code>
+````
+
+### Parsing Algorithm
+
+A correct inline code parser must:
+
+1. Detect opening backtick sequences and count their length
+1. Search for a closing sequence of **exactly the same length**
+1. Handle nested or unmatched backticks as literal content
+1. Strip one leading and one trailing space when both are present
+
+**Key implementation requirements:**
+
+- Count opening backticks and search for closing sequence of **exactly the same length**
+- Verify the closing sequence isn't part of a longer backtick run
+- Strip one leading and trailing space when both are present (CommonMark rule)
+- Treat unmatched opening sequences as literal text
+
+### Common Parsing Pitfalls
+
+1. **Greedy matching**: Using regex like `` `[^`]+` `` fails on nested backticks
+1. **Ignoring backtick count**: Treating all backtick sequences as equivalent
+1. **Missing space stripping**: Not handling `` ` code ` `` correctly
+1. **Partial matches**: Matching ` `` ` inside ` ``` ` sequences
+
+## Test Coverage for Parsers
+
+### Edge Case Categories
+
+When testing parsers, cover these categories:
+
+| Category      | Examples                                       |
+| ------------- | ---------------------------------------------- |
+| Empty/minimal | `''`, `` ` ``, ` `` `                          |
+| Boundary      | Code at start/end, only code, adjacent spans   |
+| Nested        | ``` `` `nested` `` ```, unequal counts         |
+| Whitespace    | Leading/trailing spaces, only spaces, newlines |
+| Unicode       | `café`, emoji, zero-width characters           |
+
+### Data-Driven Test Patterns
+
+Use parameterized tests for comprehensive coverage:
+
+```javascript
+describe("inline code parsing", () => {
+  const testCases = [
+    // [input, expectedOutput, description]
+    ["`code`", [{ type: "code", content: "code" }], "simple code span"],
+    ["``a`b``", [{ type: "code", content: "a`b" }], "backtick in code"],
+    ["` a `", [{ type: "code", content: "a" }], "space stripping"],
+    [
+      "`a``b`",
+      [
+        { type: "code", content: "a" },
+        { type: "code", content: "b" }
+      ],
+      "adjacent spans"
+    ]
+  ];
+
+  test.each(testCases)("%s → %j (%s)", (input, expected, _desc) => {
+    expect(parseInlineCode(input)).toEqual(expected);
+  });
+});
+```
+
+### Property-Based Testing
+
+For parser robustness, use property-based tests with libraries like `fast-check`:
+
+- **Never throws**: Parser should handle any input without throwing
+- **Content preservation**: Total output length ≤ input length (accounting for delimiters)
+- **Idempotence**: Re-parsing output yields same structure
+
+## CI/CD Integration Patterns
+
+### Fail-Safe Git Operations
+
+Structure git operations in CI to handle all edge cases:
+
+```yaml
+# GitHub Actions example
+- name: Check for changes
+  id: changes
+  run: |
+    # Handle initial commit
+    if git rev-parse HEAD~1 >/dev/null 2>&1; then
+      CHANGED_FILES=$(git diff --name-only HEAD~1 HEAD)
+    else
+      # First commit - all files are "new"
+      CHANGED_FILES=$(git ls-tree --name-only -r HEAD)
+    fi
+    echo "files=$CHANGED_FILES" >> $GITHUB_OUTPUT
+```
+
+### Parser Testing in CI
+
+Ensure parser tests run with comprehensive edge cases:
+
+```yaml
+- name: Run parser tests
+  run: |
+    npm test -- --coverage --coverageThreshold='{"global":{"branches":90}}'
+```
+
+### Handling `grep` Exit Codes
+
+`grep` returns exit code 1 when no matches are found, which fails CI pipelines:
+
+```bash
+# DANGEROUS: Fails CI when no matches
+grep "pattern" file.txt
+
+# SAFE: Handle no-match case
+grep "pattern" file.txt || true
+
+# SAFE: Use count with fallback
+COUNT=$(grep -c "pattern" file.txt 2>/dev/null || echo "0")
+```
+
+## Validation Checklist
+
+Before merging code with git commands or parsers:
+
+- [ ] Git commands handle initial/empty commits
+- [ ] Git commands work with shallow clones
+- [ ] Git commands handle detached HEAD states
+- [ ] File paths are properly quoted
+- [ ] Parsers handle empty input
+- [ ] Parsers handle malformed/unmatched delimiters
+- [ ] Parsers handle unicode and special characters
+- [ ] Tests cover boundary conditions
+- [ ] Tests use data-driven patterns for edge cases
+- [ ] CI pipelines handle `grep` exit codes properly
+
+## See Also
+
+- [Comprehensive Test Coverage](../testing/comprehensive-test-coverage.md) - Detailed testing
+  strategies
+- [Documentation Updates](../documentation/documentation-updates.md) - Keeping docs in sync
+- [Shell Pattern Matching](../../context.md#shell-pattern-matching) - Main context file patterns