TagHelperCollection Part 1: The new bits (#12504)

| [Prelude](#12503) | Part 1 | [Part
2](#12505) | [Part
3](#12506) | [Part
4](#12507) | [Part
5](#12509) |

This pull request represents all new code! It introduces a new immutable
collection type, `TagHelperCollection`, that is designed to contain
`TagHelperDescriptors`. It is built with the following principles:

1. Guarantee that collections never contain duplicate tag helpers.
2. Collections can be compared efficiently via checksums.
3. Multiple collections can be merged into a single collection
efficiently, with minimal array copying.
4. Determining whether a collection contains a tag helper is efficient.

> [!TIP]
> Since this is all new code, I recommend reviewing commit-by-commit.
Each commit represents a cohesive portion of new code.

----
CI Build:
https://dev.azure.com/dnceng/internal/_build/results?buildId=2842145&view=results
Toolset Run:
https://dev.azure.com/dnceng/internal/_build/results?buildId=2842216&view=results

Author: DustinCampbell

src/Compiler/Microsoft.AspNetCore.Razor.Language/test/TagHelperCollectionTest.cs

@@ -0,0 +1,71 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections;
+using System.Collections.Generic;
+
+namespace Microsoft.AspNetCore.Razor.Language;
+
+public abstract partial class TagHelperCollection
+{
+    public sealed partial class Builder
+    {
+        public ref struct Enumerator(Builder builder)
+        {
+            private int _index = -1;
+
+            public readonly TagHelperDescriptor Current => builder[_index];
+
+            public bool MoveNext()
+            {
+                if (_index < builder.Count - 1)
+                {
+                    _index++;
+                    return true;
+                }
+
+                return false;
+            }
+
+            public void Reset()
+            {
+                _index = -1;
+            }
+
+            public void Dispose()
+            {
+                Reset();
+            }
+        }
+
+        private sealed class EnumeratorImpl(Builder builder) : IEnumerator<TagHelperDescriptor>
+        {
+            private int _index = -1;
+
+            public TagHelperDescriptor Current => builder[_index];
+
+            object IEnumerator.Current => Current;
+
+            public bool MoveNext()
+            {
+                if (_index < builder.Count - 1)
+                {
+                    _index++;
+                    return true;
+                }
+
+                return false;
+            }
+
+            public void Reset()
+            {
+                _index = -1;
+            }
+
+            public void Dispose()
+            {
+                _index = -1;
+            }
+        }
+    }
+}

src/Compiler/Microsoft.CodeAnalysis.Razor.Compiler/src/Language/TagHelperCollection.Builder.Enumerator.cs

@@ -0,0 +1,150 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Collections;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Threading;
+using Microsoft.AspNetCore.Razor.PooledObjects;
+using Microsoft.AspNetCore.Razor.Utilities;
+
+namespace Microsoft.AspNetCore.Razor.Language;
+
+public abstract partial class TagHelperCollection
+{
+    public sealed partial class Builder : ICollection<TagHelperDescriptor>, IReadOnlyList<TagHelperDescriptor>, IDisposable
+    {
+        // Create new pooled builders and sets with a larger initial capacity to limit growth.
+        private const int InitialCapacity = 256;
+
+        // Builders and sets are typically large, so allow them to stay larger when returned to their pool.
+        private const int MaximumObjectSize = 2048;
+
+        private static readonly ArrayBuilderPool<TagHelperDescriptor> s_arrayBuilderPool =
+            ArrayBuilderPool<TagHelperDescriptor>.Create(InitialCapacity, MaximumObjectSize);
+
+        private ImmutableArray<TagHelperDescriptor>.Builder _items;
+        private HashSet<Checksum> _set;
+
+        public Builder()
+        {
+            _items = s_arrayBuilderPool.Get();
+            _set = ChecksumSetPool.Default.Get();
+        }
+
+        public void Dispose()
+        {
+            var items = Interlocked.Exchange(ref _items, null!);
+            if (items is not null)
+            {
+                s_arrayBuilderPool.Return(items);
+            }
+
+            var set = Interlocked.Exchange(ref _set, null!);
+            if (set is not null)
+            {
+                ChecksumSetPool.Default.Return(set);
+            }
+        }
+
+        public bool IsEmpty => Count == 0;
+
+        public int Count => _items.Count;
+
+        public bool IsReadOnly => false;
+
+        public TagHelperDescriptor this[int index]
+        {
+            get
+            {
+                ArgHelper.ThrowIfNegative(index);
+                ArgHelper.ThrowIfGreaterThanOrEqual(index, Count);
+
+                return _items[index];
+            }
+        }
+
+        public bool Add(TagHelperDescriptor item)
+        {
+            if (!_set.Add(item.Checksum))
+            {
+                return false;
+            }
+
+            _items.Add(item);
+            return true;
+        }
+
+        void ICollection<TagHelperDescriptor>.Add(TagHelperDescriptor item)
+            => Add(item);
+
+        public void AddRange(TagHelperCollection items)
+        {
+            foreach (var item in items)
+            {
+                if (_set.Add(item.Checksum))
+                {
+                    _items.Add(item);
+                }
+            }
+        }
+
+        public void AddRange(ReadOnlySpan<TagHelperDescriptor> span)
+        {
+            foreach (var item in span)
+            {
+                if (_set.Add(item.Checksum))
+                {
+                    _items.Add(item);
+                }
+            }
+        }
+
+        public void AddRange(IEnumerable<TagHelperDescriptor> source)
+        {
+            foreach (var item in source)
+            {
+                if (_set.Add(item.Checksum))
+                {
+                    _items.Add(item);
+                }
+            }
+        }
+
+        public void Clear()
+        {
+            _items.Clear();
+            _set.Clear();
+        }
+
+        public bool Contains(TagHelperDescriptor item)
+            => _set.Contains(item.Checksum);
+
+        public void CopyTo(TagHelperDescriptor[] array, int arrayIndex)
+            => _items.CopyTo(array, arrayIndex);
+
+        public bool Remove(TagHelperDescriptor item)
+            => _set.Remove(item.Checksum) && _items.Remove(item);
+
+        public TagHelperCollection ToCollection()
+        {
+            if (_items.Count == 0)
+            {
+                return Empty;
+            }
+
+            var array = _items.ToImmutable();
+            return new SingleSegmentCollection(array.AsMemory());
+        }
+
+        public Enumerator GetEnumerator()
+            => new(this);
+
+        IEnumerator<TagHelperDescriptor> IEnumerable<TagHelperDescriptor>.GetEnumerator()
+            => new EnumeratorImpl(this);
+
+        IEnumerator IEnumerable.GetEnumerator()
+            => new EnumeratorImpl(this);
+    }
+}

src/Compiler/Microsoft.CodeAnalysis.Razor.Compiler/src/Language/TagHelperCollection.Builder.cs

@@ -0,0 +1,61 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Razor.PooledObjects;
+using Microsoft.AspNetCore.Razor.Utilities;
+
+namespace Microsoft.AspNetCore.Razor.Language;
+
+public abstract partial class TagHelperCollection
+{
+    private sealed class ChecksumSetPool : CustomObjectPool<HashSet<Checksum>>
+    {
+        private const int MaximumObjectSize = 2048;
+
+        public static readonly ChecksumSetPool Default = new(Policy.Instance, DefaultPoolSize);
+
+        private ChecksumSetPool(PooledObjectPolicy policy, Optional<int> poolSize)
+            : base(policy, poolSize)
+        {
+        }
+
+        private sealed class Policy : PooledObjectPolicy
+        {
+            public static readonly Policy Instance = new();
+
+            private Policy()
+            {
+            }
+
+            public override HashSet<Checksum> Create()
+            {
+#if NET
+                return new(capacity: MaximumObjectSize);
+#else
+                return [];
+#endif
+            }
+
+            public override bool Return(HashSet<Checksum> set)
+            {
+                var count = set.Count;
+                set.Clear();
+
+                if (count > MaximumObjectSize)
+                {
+#if NET9_0_OR_GREATER
+                    set.TrimExcess(MaximumObjectSize);
+#elif NET8_0
+                    set.TrimExcess();
+                    set.EnsureCapacity(MaximumObjectSize);
+#else
+                    set.TrimExcess();
+#endif
+                }
+
+                return true;
+            }
+        }
+    }
+}

src/Compiler/Microsoft.CodeAnalysis.Razor.Compiler/src/Language/TagHelperCollection.ChecksumSetPool.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Microsoft.AspNetCore.Razor.Utilities;
+
+namespace Microsoft.AspNetCore.Razor.Language;
+
+public abstract partial class TagHelperCollection
+{
+    /// <summary>
+    ///  Represents an immutable, empty collection of tag helpers.
+    /// </summary>
+    private sealed class EmptyCollection : TagHelperCollection
+    {
+        public static readonly EmptyCollection Instance = new();
+
+        private EmptyCollection()
+        {
+        }
+
+        public override int Count => 0;
+
+        public override TagHelperDescriptor this[int index]
+            => throw new IndexOutOfRangeException();
+
+        internal override Checksum Checksum => Checksum.Null;
+
+        public override int IndexOf(TagHelperDescriptor item) => -1;
+
+        public override void CopyTo(Span<TagHelperDescriptor> destination)
+        {
+            // Nothing to copy.
+        }
+
+        protected override int SegmentCount => 0;
+
+        protected override ReadOnlyMemory<TagHelperDescriptor> GetSegment(int index)
+            => Assumed.Unreachable<ReadOnlyMemory<TagHelperDescriptor>>();
+    }
+}