feat(utilities): add runtime helper utilities

[ANcpLua]

Summary

• Reuse dev/sync-published-ancplua-versions for the unmerged helper work after PR Sync published ANcpLua package versions #111 already merged the version-sync commit.
• Rebase the branch onto current origin/main so this PR is a single runtime-helper commit on top of feat(utilities): add TryResult helpers #112 / v2.2.6.
• Add small utility surfaces for delegate disposables, empty enumerators, read-only empty collections, weak references, formatting/copy helpers, reader-writer lock scopes, and enumerable compatibility aliases.
• Tighten the lock-scope implementation during self-review by using sealed disposable guards with Interlocked.Exchange, avoiding mutable-struct copy double-dispose behavior.

Validation

• git diff --check origin/main...HEAD
• dotnet test --project tests/ANcpLua.Roslyn.Utilities.Testing.Tests/ANcpLua.Roslyn.Utilities.Testing.Tests.csproj passed: 38 total, 0 failed.
• dotnet restore ANcpLua.Roslyn.Utilities.slnx
• dotnet build ANcpLua.Roslyn.Utilities.slnx -c Release --no-restore -p:Version=0.0.0-local
• dotnet pack src/ANcpLua.Roslyn.Utilities/ANcpLua.Roslyn.Utilities.csproj -c Release -o artifacts/pr-pack-sync -p:Version=0.0.0-local --no-build
• dotnet pack src/ANcpLua.Roslyn.Utilities.Sources/ANcpLua.Roslyn.Utilities.Sources.csproj -c Release -o artifacts/pr-pack-sync -p:Version=0.0.0-local --no-build
• Verified the source package contains the new helper files, including DelegateDisposable.cs, Enumerator*.cs, FormattingExtensions.cs, ReadOnly*.cs, ReaderWriterLockSlimExtensions.cs, WeakReferenceExtensions.cs, and the current TryResult.cs from main.

Notes

• Existing full-solution test caveat remains from PR feat(utilities): add TryResult helpers #112 triage: dotnet test --solution ANcpLua.Roslyn.Utilities.slnx fails in ANcpLua.Roslyn.Utilities.ExtensibleEnumMirror.Tests with generated namespace TestNs.TestNs; / CS8955 on origin/main, so I used the focused helper tests plus the CI-shaped Release build for this PR.

Summary by CodeRabbit

• New Features

  • Added lock scope management utilities for reader/writer synchronization
  • Added enumerable sequence helpers: Only, OnlyOrDefault, NotNull, Join methods
  • Added weak reference target retrieval extensions
  • Added low-allocation formatting and span copy utilities
  • Added cached empty collection and enumerator factories
  • Added dictionary enumerator adapter for key-value pair sequences

• Tests

  • Added comprehensive test suite validating utility APIs and error handling

[github-actions]

@coderabbitai autofix

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This pull request introduces utility APIs across nine new files in ANcpLua.Roslyn.Utilities. The additions include thread-safe disposal primitives (DelegateDisposable), cached empty collection/enumerator factories (ReadOnlyCollection, ReadOnlyDictionary, Enumerator), enumerable compatibility methods (Only, OnlyOrDefault, NotNull, Join), formatting/copy helpers for spans and string builders, weak reference adapters, reader/writer lock scope guards, and a dictionary enumerator adapter. All public-facing types and methods are gated by the ANCPLUA_ROSLYN_PUBLIC compilation symbol for conditional visibility. A comprehensive test suite validates the APIs across disposal guarantees, locking semantics, weak reference liveness, copy bounds, caching, and null-argument contracts.

🚥 Pre-merge checks | ✅ 8 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
No Null-Forgiving Operator Without Justification	⚠️ Warning	Four null-forgiving operators added without inline comments: EnumerableExtensions.cs lines 256, 276; Enumerator.cs lines 79, 107. Policy requires inline comment justification for each suppression.	Add inline comments justifying each ! operator, or refactor per review comments: replace default! with exceptions and use [MaybeNullWhen(false)] instead of result!.

✅ Passed checks (8 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	Title follows conventional commits format (feat prefix), is under 72 characters (45 chars), contains no trailing period, and accurately describes the main change: addition of runtime helper utilities across multiple new files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
No Datetime.Now/Utcnow	✅ Passed	No DateTime.Now or DateTime.UtcNow usage detected in any added/modified C# files. All 10 files scanned clean.
No .Result/.Wait() Blocking Async	✅ Passed	No .Result, .Wait(), or .GetAwaiter().GetResult() blocking patterns found in any of the 10 added/modified C# files. Scan validated against files with actual async code.
No Isourcegenerator	✅ Passed	No ISourceGenerator implementations detected. All 10 new files are runtime utilities—no source generators added.
Sources Public Types Must Be Internal	✅ Passed	No C# files added to src/ANcpLua.Roslyn.Utilities.Sources/. New utilities use ANCPLUA_ROSLYN_PUBLIC conditional compilation. Transform-Sources.ps1 automatically converts public→internal at pack time.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.

[github-actions]

@coderabbitai autofix

[ANcpLua]

Self-review findings: no blocking issues in this PR diff.

Checked scope:

• Branch had an already-merged PR (#111), but the branch was reused and had a newer unmerged helper commit.
• Rebasing onto current origin/main dropped the old version-sync commit and left one runtime-helper commit.
• PR now contains only helper additions/aliases plus focused tests.

Self-review changes made before this review:

• Converted reader/writer lock scope guards from mutable structs to sealed disposable classes using Interlocked.Exchange, avoiding double-exit behavior if the disposable reference is aliased.
• Replaced a source-file collection expression in ReadOnlyCollection.Empty<T> with global::System.Array.Empty<T>() so the source package does not force collection-expression syntax on consumers.
• Removed the Chasm-derived wording from the commit message; this PR now describes the local helper surface directly.

Validation:

• git diff --check origin/main...HEAD and working-tree git diff --check
• dotnet test --project tests/ANcpLua.Roslyn.Utilities.Testing.Tests/ANcpLua.Roslyn.Utilities.Testing.Tests.csproj passed: 38 total, 0 failed
• dotnet restore ANcpLua.Roslyn.Utilities.slnx
• dotnet build ANcpLua.Roslyn.Utilities.slnx -c Release --no-restore -p:Version=0.0.0-local passed with 0 warnings, 0 errors
• runtime and source-only package pack commands passed
• source package inspection confirmed the new helper files are included and ReadOnlyCollection.cs transforms to internal source using global::System.Array.Empty<T>()

Known existing issue, not introduced here: full-solution dotnet test --solution still has the ExtensibleEnumMirror namespace TestNs.TestNs / CS8955 issue previously reproduced on origin/main.

[coderabbitai]

Note

Autofix is a beta feature. Expect some limitations and changes as we gather feedback and continue to improve it.

Autofix skipped. No unresolved CodeRabbit review comments with fix instructions found.