ersatztv/ErsatzTV.Tests/Integration/SongIndexerMetadataMutationTests.cs

using System.Reflection;
using ErsatzTV.Core.Domain;
using ErsatzTV.Core.Interfaces.Metadata;
using ErsatzTV.Core.Interfaces.Repositories;
using ErsatzTV.Core.Search;
using ErsatzTV.Infrastructure.Data;
using ErsatzTV.Infrastructure.Extensions;
using ErsatzTV.Infrastructure.Search;
using ErsatzTV.Tests.Support;
using Lucene.Net.Analysis.Standard;
using Lucene.Net.Index;
using Lucene.Net.Store;
using Lucene.Net.Util;
using Microsoft.EntityFrameworkCore;
using Microsoft.Extensions.Logging;
using NSubstitute;
using NUnit.Framework;
using Shouldly;

namespace ErsatzTV.Tests.Integration;

/// <summary>
///     ersatztv#701, EXECUTED against a real <see cref="TvContext" /> on SQLite.
///     <para>
///         <b>The defect.</b> <c>LuceneSearchIndex.UpdateSong</c> opened with
///         <c>metadata.AlbumArtists ??= []; metadata.Artists ??= [];</c>. Unlike the navigation
///         collections guarded the same way all around them, these two are SCALAR COLUMNS: the whole
///         list lives in one column, so the property IS the column value. They are two of EIGHT such
///         columns in the model — the population is derived from the MODEL CONFIGURATION (EF-native
///         primitive collections plus the six <c>HasConversion&lt;*CollectionValueConverter&gt;</c>
///         columns on <c>ProgramScheduleAlternate</c>/<c>PlayoutTemplate</c>), NOT by grepping the
///         domain classes for <c>IList&lt;string&gt;</c>, which finds only two of the eight. See
///         the decision record <c>media.nullable-primitive-collection-mutation</c>.
///         Assigning one on a TRACKED entity flips it to <see cref="EntityState.Modified" />, and the next
///         <c>SaveChanges</c> writes <c>[]</c> over what the database held as <c>NULL</c> — the exact
///         mechanism demonstrated in ersatztv#691, which is why that issue's
///         entity-level guard was reverted in favour of guarding at the READ SITE.
///     </para>
///     <para>
///         <b>Why the fixture loads the song TRACKED even though production does not.</b> Both feeds into
///         the indexer are <c>AsNoTracking()</c> today — <c>SearchRepository.GetItemToIndex</c> and
///         <c>SearchRepository.GetAllSongs</c> — so no shipped caller loses data. That is a property of
///         today's two callers, not of the indexer, and it is exactly what ersatztv#691 recorded as "a
///         loaded gun". This fixture therefore pins the INDEXER's own contract: handed a tracked entity it
///         must not mutate it. Run against the real pre-fix file, the FIRST of the numbered assertions
///         below fails (<c>metadata.Artists should be null but was []</c>) and the run stops there;
///         reaching the persistence half needs a probe variant with assertions 1 and 2 replaced by
///         prints, which reports <c>Modified</c> and the column moving from <c>NULL</c> to <c>[]</c>.
///         Each was separately shown discriminating. A future caller that drops <c>AsNoTracking</c>
///         therefore cannot reintroduce the data loss silently.
///     </para>
///     <para>
///         The Lucene <see cref="IndexWriter" /> is injected into the private field rather than obtained via
///         <c>Initialize</c>, because <c>Initialize</c> writes to <c>FileSystemLayout.SearchIndexFolder</c> —
///         a process-wide static resolved once from <c>ETV_CONFIG_FOLDER</c>, i.e. the developer's real
///         application data folder. Letting the writer throw instead is NOT an option here: the
///         <c>catch</c> in <c>UpdateSong</c> assigns <c>metadata.Song = null</c>, which would itself dirty
///         the entity under test and make the probe report the wrong cause.
///     </para>
/// </summary>
[TestFixture]
public class SongIndexerMetadataMutationTests
{
    [Test]
    public async Task UpdateSong_Must_Not_Mutate_Nullable_Artists_On_A_Tracked_Entity()
    {
        await using var harness = await InMemoryTvContext.CreateAsync();

        int metadataId;
        await using (TvContext context = harness.CreateContext())
        {
            var library = new LocalLibrary { Name = "Music", MediaKind = LibraryMediaKind.Songs };
            context.Add(library);
            await context.SaveChangesAsync();

            var libraryPath = new LibraryPath { Path = "/music", LibraryId = library.Id };
            context.Add(libraryPath);
            await context.SaveChangesAsync();

            var song = new Song
            {
                LibraryPathId = libraryPath.Id,
                MediaVersions = [],
                SongMetadata =
                [
                    new SongMetadata
                    {
                        MetadataKind = MetadataKind.Fallback,
                        Title = "Untagged Track",
                        SortTitle = "untagged track",
                        DateAdded = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc),

                        // The shape FallbackMetadataProvider.GetSongMetadata leaves behind: it never
                        // assigns either primitive collection, so both columns persist as NULL.
                        Artists = null!,
                        AlbumArtists = null!,

                        Genres = [],
                        Tags = [],
                        Studios = [],
                        Actors = [],
                        Artwork = [],
                        Guids = []
                    }
                ]
            };

            context.Add(song);
            await context.SaveChangesAsync();
            metadataId = song.SongMetadata[0].Id;
        }

        // The seed must actually have produced NULL columns, or every assertion below is vacuous.
        (await ReadRawArtists(harness, metadataId)).ShouldBeNull();

        await using (TvContext context = harness.CreateContext())
        {
            // Deliberately TRACKED -- see the fixture docstring.
            Song tracked = await context.Songs
                .IncludeForSearch()
                .AsSplitQuery()
                .SingleAsync();

            SongMetadata metadata = tracked.SongMetadata[0];
            metadata.Artists.ShouldBeNull("EF must materialize the NULL column as null, not as an empty list");

            // UpdateSong wraps its whole body in a catch that logs a warning and assigns
            // `metadata.Song = null` -- which severs a required relationship and cascades the metadata to
            // Deleted. A silently-exercised catch would therefore make every assertion below report the
            // wrong cause, so the logger fails the test instead of swallowing.
            var logger = new ThrowOnWarningLogger<LuceneSearchIndex>();
            var index = new LuceneSearchIndex(
                new SearchQueryParser(
                    Substitute.For<ISmartCollectionCache>(),
                    Substitute.For<ILogger<SearchQueryParser>>()),
                logger);

            using var directory = new RAMDirectory();
            using var writer = new IndexWriter(
                directory,
                new IndexWriterConfig(LuceneVersion.LUCENE_48, new StandardAnalyzer(LuceneVersion.LUCENE_48)));

            typeof(LuceneSearchIndex)
                .GetField("_writer", BindingFlags.NonPublic | BindingFlags.Instance)!
                .SetValue(index, writer);

            // A bare substitute returns null from GetAllLanguageCodes, which NPEs inside AddLanguages and
            // would divert the run into the catch above.
            var languageCodeService = Substitute.For<ILanguageCodeService>();
            languageCodeService.GetAllLanguageCodes(Arg.Any<List<string>>()).Returns([]);
            languageCodeService.GetAllLanguageCodes(Arg.Any<string>()).Returns([]);

            await index.UpdateItems(
                Substitute.For<ISearchRepository>(),
                Substitute.For<IFallbackMetadataProvider>(),
                languageCodeService,
                [tracked]);

            logger.Failure.ShouldBeNull("UpdateSong threw and its catch ran, so this probe measured the "
                + "error path rather than the indexing path");

            // POSITIVE CONTROL. Every assertion below asserts that something did NOT happen, so all of
            // them hold vacuously if UpdateSong never ran at all -- and it silently stops running if a
            // future refactor gates UpdateItems on `_initialized`, which this fixture deliberately
            // bypasses by injecting the writer. Verified BOTH ways by adding
            // `if (!_initialized) { return Unit.Default; }` to UpdateItems (a bare `return;` does not
            // compile there -- CS0126): with this line present it is the only failure, and with it
            // removed the whole test PASSES while the code under test is unreachable.
            // NumDocs == 1 proves the song-indexing path ran; it does NOT prove the artist loops
            // specifically ran, which would need a second seeded song asserting ArtistField.
            writer.NumDocs.ShouldBe(1, "UpdateSong did not index the song, so the assertions below "
                + "would pass without exercising the code under test");

            // 1. The indexer left the entity alone.
            metadata.Artists.ShouldBeNull();
            metadata.AlbumArtists.ShouldBeNull();

            // 2. ...so EF has nothing to persist. This is the assertion that fails loudly the day the
            //    mutation returns, even if a later refactor stopped the value from being observable above.
            context.Entry(metadata).State.ShouldBe(EntityState.Unchanged);

            // 3. And the save that a real caller would go on to make does not rewrite the column.
            await context.SaveChangesAsync();
        }

        (await ReadRawArtists(harness, metadataId)).ShouldBeNull();
    }

    private static async Task<object?> ReadRawArtists(InMemoryTvContext harness, int metadataId)
    {
        await using TvContext context = harness.CreateContext();
        await using var command = context.Database.GetDbConnection().CreateCommand();
        command.CommandText = $"SELECT Artists FROM SongMetadata WHERE Id = {metadataId}";
        object? value = await command.ExecuteScalarAsync();

        // ExecuteScalar returns CLR null both for "the column is NULL" and for "there is no such row",
        // and the second is reachable: UpdateSong's catch assigns metadata.Song = null, which severs a
        // required relationship and cascades the row to Deleted, so a SaveChanges on the error path
        // DELETES it and a plain null check would pass for the wrong reason.
        if (value is null)
        {
            Assert.Fail($"SongMetadata row {metadataId} no longer exists, so its Artists column cannot "
                + "be read -- the probe measured a deleted row rather than a preserved NULL.");
        }

        return value is DBNull ? null : value;
    }
}