Merge branch 'dev'

Author: Noggog

DEVELOPMENT.md

@@ -137,6 +137,31 @@ cd Mutagen.Bethesda.Generator.All/bin/Debug/net8.0
 
 The generators use relative paths like `../../../../Mutagen.Bethesda.{Game}/Records` to locate project files. Running from the build output directory ensures these relative paths resolve correctly to the repository structure.
 
+## Project File Management
+
+### Adding New Files to Projects
+
+**Important**: Most projects in this repository use `<EnableDefaultCompileItems>False</EnableDefaultCompileItems>`, which means all source files must be explicitly listed in the `.csproj` file. This is necessary to properly nest generated code files under their corresponding XML definition files.
+
+When adding new `.cs` files to a project:
+
+1. **Find the correct location** in the `.csproj` file (files are typically grouped by directory/feature)
+2. **Add a `<Compile Include="...">` element** with the file path
+3. **For generated files only**: Add a `<DependentUpon>...</DependentUpon>` element to nest it under the XML file
+
+Example:
+```xml
+<!-- Regular file (no nesting) -->
+<Compile Include="Plugins\Analysis\DI\MultiModFileReader.cs" />
+
+<!-- Generated file (nested under XML) -->
+<Compile Include="Records\SkyrimMod_Generated.cs">
+  <DependentUpon>SkyrimMod.xml</DependentUpon>
+</Compile>
+```
+
+If you create a new file and the build can't find it, check that it's been added to the `.csproj` file.
+
 ## Development Workflow
 
 ### Always Verify Your Changes
@@ -156,6 +181,18 @@ dotnet test Mutagen.UnitTests.sln
 
 This ensures your changes don't break the build or existing functionality.
 
+### File System Operations
+- **NEVER redirect to `nul`** - On Windows, `2>nul` creates unwanted files that Git tracks
+- Use proper null redirection: `2>/dev/null` (works on Windows with bash)
+- For temporary files, use `.claude/` subfolder or designated temp directories that are gitignored
+- Example: `ls directory 2>/dev/null || echo "Not found"` instead of `dir directory 2>nul`
+- **NEVER use `sed` for bulk find/replace** - `sed` does not preserve Windows CRLF line endings, creating massive spurious diffs
+  - On Windows, `sed -i` converts CRLF to LF, causing every line to show as changed in git
+  - Use targeted edits with the Edit tool instead of global sed replacements
+  - If you must do bulk replacements, only use tools that preserve line endings (e.g., PowerShell with `-Raw` and explicit encoding)
+  - Example (incorrect): `find . -name "*.cs" -exec sed -i 's/OldName/NewName/g' {} \;` - creates CRLF→LF changes on every touched file
+  - Example (correct): Use Edit tool on each file individually, or ask user to use IDE refactoring tools
+
 ## Releases
 
 ### Packaging
@@ -189,6 +226,35 @@ Mutagen uses AutoFixture with custom builders to automatically generate properly
 - If you want, you can use `[Theory, MutagenModAutoData]` which will allow injection of mods, and records that are added to the latest mod.
 - AutoFixture will inject properly configured `SkyrimMod`, `ModKey`, `FormKey`, etc. as test parameters
 
+## Coding Practices
+
+### Avoid Using `dynamic`
+
+Do not use `dynamic` when possible. The codebase provides proper interfaces and generic methods that should be used instead. Using `dynamic` bypasses compile-time type checking and can lead to runtime errors.
+
+### Prefer ModPath Over DirectoryPath + ModKey
+
+When working with paths to mod files, prefer using `ModPath` instead of separate `DirectoryPath` and `ModKey` parameters. `ModPath` is essentially a string path that is expected to point to a mod file, and includes the associated `ModKey`.
+
+```cs
+// Preferred - uses ModPath
+public void ProcessMod(ModPath modPath)
+{
+    var modKey = modPath.ModKey;
+    var filePath = modPath.Path;
+    // ...
+}
+
+// Avoid - separate parameters
+public void ProcessMod(DirectoryPath folder, ModKey modKey)
+{
+    var filePath = Path.Combine(folder.Path, modKey.FileName);
+    // ...
+}
+```
+
+`ModPath` provides better API ergonomics and ensures the path and ModKey stay in sync.
+
 ## Contributing
 
 See the main README.md and official documentation for contribution guidelines.

Directory.Packages.props

@@ -33,10 +33,10 @@
     <PackageVersion Include="Microsoft.Reactive.Testing" Version="6.0.2" />
     <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" PrivateAssets="All" />
     <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
-    <PackageVersion Include="Noggog.Autofac" Version="3.1.0" />
-    <PackageVersion Include="Noggog.CSharpExt" Version="3.1.0" />
-    <PackageVersion Include="Noggog.Testing" Version="3.1.0" />
-    <PackageVersion Include="Noggog.WPF" Version="3.1.0" />
+    <PackageVersion Include="Noggog.Autofac" Version="3.2.0-alpha.6" />
+    <PackageVersion Include="Noggog.CSharpExt" Version="3.2.0-alpha.6" />
+    <PackageVersion Include="Noggog.Testing" Version="3.2.0-alpha.6" />
+    <PackageVersion Include="Noggog.WPF" Version="3.2.0-alpha.6" />
     <PackageVersion Include="ReactiveUI" Version="21.0.1" />
     <PackageVersion Include="ReactiveUI.Fody" Version="19.5.41" />
     <PackageVersion Include="ReactiveMarbles.ObservableEvents.SourceGenerator" Version="1.3.1" PrivateAssets="all" />

Mutagen.Bethesda.Core.UnitTests/Json/JsonConverterTests.cs

@@ -1,3 +1,4 @@
+using Loqui;
 using Shouldly;
 using Mutagen.Bethesda.Json;
 using Mutagen.Bethesda.Plugins;
@@ -12,6 +13,12 @@ namespace Mutagen.Bethesda.UnitTests.Json;
 
 public class JsonConverterTests
 {
+    static JsonConverterTests()
+    {
+        Warmup.Init();
+        LoquiRegistration.Register(TestMajorRecord_Registration.Instance);
+    }
+
     #region FormKey
     class FormKeyClass
     {
@@ -174,7 +181,7 @@ public void FormKeyConverter_FormLink_Serialize()
             Getter = new FormLink<ITestMajorRecordGetter>(TestConstants.Form2)
         };
         JsonConvert.SerializeObject(toSerialize, settings)
-            .ShouldBe($"{{\"Direct\":\"{toSerialize.Direct.FormKey}\",\"Setter\":\"{toSerialize.Direct.FormKey}\",\"Getter\":\"{toSerialize.Direct.FormKey}\"}}");
+            .ShouldBe($"{{\"Direct\":\"{toSerialize.Direct.FormKey}<TestGame.TestMajorRecord>\",\"Setter\":\"{toSerialize.Direct.FormKey}<TestGame.TestMajorRecord>\",\"Getter\":\"{toSerialize.Direct.FormKey}<TestGame.TestMajorRecord>\"}}");
     }
 
     [Fact]
@@ -188,7 +195,7 @@ public void FormKeyConverter_FormLink_Deserialize()
             Setter = new FormLink<ITestMajorRecordGetter>(TestConstants.Form2),
             Getter = new FormLink<ITestMajorRecordGetter>(TestConstants.Form2)
         };
-        var toDeserialize = $"{{\"Direct\":\"{target.Direct.FormKey}\",\"Setter\":\"{target.Direct.FormKey}\",\"Getter\":\"{target.Direct.FormKey}\"}}";
+        var toDeserialize = $"{{\"Direct\":\"{target.Direct.FormKey}<TestGame.TestMajorRecord>\",\"Setter\":\"{target.Direct.FormKey}<TestGame.TestMajorRecord>\",\"Getter\":\"{target.Direct.FormKey}<TestGame.TestMajorRecord>\"}}";
         JsonConvert.DeserializeObject<FormLinkClass>(toDeserialize, settings)!
             .Direct
             .ShouldBe(target.Direct);
@@ -206,6 +213,21 @@ public void FormKeyConverter_FormLink_Deserialize_Missing()
             .ShouldBe(target.Direct);
     }
 
+    [Fact]
+    public void FormKeyConverter_FormLink_Serialize_Null()
+    {
+        var settings = new JsonSerializerSettings();
+        settings.Converters.Add(new FormKeyJsonConverter());
+        var toSerialize = new FormLinkClass()
+        {
+            Direct = new FormLink<ITestMajorRecordGetter>(FormKey.Null),
+            Setter = new FormLink<ITestMajorRecordGetter>(FormKey.Null),
+            Getter = new FormLink<ITestMajorRecordGetter>(FormKey.Null)
+        };
+        JsonConvert.SerializeObject(toSerialize, settings)
+            .ShouldBe($"{{\"Direct\":\"Null<TestGame.TestMajorRecord>\",\"Setter\":\"Null<TestGame.TestMajorRecord>\",\"Getter\":\"Null<TestGame.TestMajorRecord>\"}}");
+    }
+
     [Fact]
     public void FormKeyConverter_FormLink_Deserialize_Null()
     {
@@ -217,7 +239,7 @@ public void FormKeyConverter_FormLink_Deserialize_Null()
             Setter = new FormLink<ITestMajorRecordGetter>(FormKey.Null),
             Getter = new FormLink<ITestMajorRecordGetter>(FormKey.Null)
         };
-        var toDeserialize = $"{{\"Direct\":\"Null\",\"Setter\":\"Null\",\"Getter\":\"Null\"}}";
+        var toDeserialize = $"{{\"Direct\":\"Null<TestGame.TestMajorRecord>\",\"Setter\":\"Null<TestGame.TestMajorRecord>\",\"Getter\":\"Null<TestGame.TestMajorRecord>\"}}";
         JsonConvert.DeserializeObject<FormLinkClass>(toDeserialize, settings)!
             .Direct
             .ShouldBe(target.Direct);
@@ -283,7 +305,7 @@ public void FormKeyConverter_FormLink_Deserialize_Empty()
     //         Member = new FormLink<ITestMajorRecordGetter>(FormKey.Null)
     //     };
     //     JsonConvert.SerializeObject(toSerialize, settings)
-    //         .ShouldBe($"{{\"Member\":\"Null\"}}");
+    //         .ShouldBe($"{{\"Member\":\"Null<TestGame.TestMajorRecord>\"}}");
     // }
     //
     // [Fact]
@@ -295,7 +317,7 @@ public void FormKeyConverter_FormLink_Deserialize_Empty()
     //     {
     //         Member = new FormLink<ITestMajorRecordGetter>(TestConstants.Form2)
     //     };
-    //     var toDeserialize = $"{{\"Member\":\"{target.Member.FormKey}\"}}";
+    //     var toDeserialize = $"{{\"Member\":\"{target.Member.FormKey}<TestGame.TestMajorRecord>\"}}";
     //     JsonConvert.DeserializeObject<NullableFormLinkClass>(toDeserialize, settings)!
     //         .Member
     //         .ShouldBe(target.Member);
@@ -329,7 +351,7 @@ public void FormKeyConverter_FormLink_Deserialize_Empty()
     // {
     //     var settings = new JsonSerializerSettings();
     //     settings.Converters.Add(new FormKeyJsonConverter());
-    //     var toDeserialize = $"{{\"Member\":\"Null\"}}";
+    //     var toDeserialize = $"{{\"Member\":\"Null<TestGame.TestMajorRecord>\"}}";
     //     JsonConvert.DeserializeObject<NullableFormLinkClass>(toDeserialize, settings)!
     //         .Member!.IsNull
     //         .ShouldBeTrue();
@@ -352,7 +374,7 @@ public void FormKeyConverter_FormLinkNullable_Serialize()
             Member = new FormLinkNullable<ITestMajorRecordGetter>(TestConstants.Form2)
         };
         JsonConvert.SerializeObject(toSerialize, settings)
-            .ShouldBe($"{{\"Member\":\"{toSerialize.Member.FormKey}\"}}");
+            .ShouldBe($"{{\"Member\":\"{toSerialize.Member.FormKey}<TestGame.TestMajorRecord>\"}}");
     }
 
     [Fact]
@@ -365,7 +387,7 @@ public void FormKeyConverter_FormLinkNullable_Serialize_Null()
             Member = new FormLinkNullable<ITestMajorRecordGetter>(default(FormKey?))
         };
         JsonConvert.SerializeObject(toSerialize, settings)
-            .ShouldBe($"{{\"Member\":null}}");
+            .ShouldBe($"{{\"Member\":\"Null<TestGame.TestMajorRecord>\"}}");
     }
 
     [Fact]
@@ -378,7 +400,7 @@ public void FormKeyConverter_FormLinkNullable_Serialize_NullFormKey()
             Member = new FormLinkNullable<ITestMajorRecordGetter>(FormKey.Null)
         };
         JsonConvert.SerializeObject(toSerialize, settings)
-            .ShouldBe($"{{\"Member\":\"Null\"}}");
+            .ShouldBe($"{{\"Member\":\"Null<TestGame.TestMajorRecord>\"}}");
     }
 
     [Fact]
@@ -390,7 +412,7 @@ public void FormKeyConverter_FormLinkNullable_Deserialize()
         {
             Member = new FormLinkNullable<ITestMajorRecordGetter>(TestConstants.Form2)
         };
-        var toDeserialize = $"{{\"Member\":\"{target.Member.FormKey}\"}}";
+        var toDeserialize = $"{{\"Member\":\"{target.Member.FormKey}<TestGame.TestMajorRecord>\"}}";
         JsonConvert.DeserializeObject<FormLinkNullableClass>(toDeserialize, settings)!
             .Member
             .ShouldBe(target.Member);
@@ -447,7 +469,7 @@ public void FormKeyConverter_FormLinkNullable_Deserialize_FormKeyNull()
         {
             Member = new FormLinkNullable<ITestMajorRecordGetter>(FormKey.Null)
         };
-        var toDeserialize = $"{{\"Member\":\"Null\"}}";
+        var toDeserialize = $"{{\"Member\":\"Null<TestGame.TestMajorRecord>\"}}";
         JsonConvert.DeserializeObject<FormLinkNullableClass>(toDeserialize, settings)!
             .Member
             .ShouldBe(target.Member);
@@ -547,15 +569,14 @@ public void FormLinkInformationConverter_FormLink_Deserialize_Missing()
     [Fact]
     public void FormLinkInformationConverter_FormLink_Deserialize_Null()
     {
-        Warmup.Init();
         var settings = new JsonSerializerSettings();
         settings.Converters.Add(new FormKeyJsonConverter());
         var target = new FormLinkInformationClass()
         {
-            Interface = new FormLinkInformation(FormKey.Null, typeof(IMajorRecordGetter)),
-            Direct = new FormLinkInformation(FormKey.Null, typeof(IMajorRecordGetter)),
+            Interface = new FormLinkInformation(FormKey.Null, typeof(ITestMajorRecordGetter)),
+            Direct = new FormLinkInformation(FormKey.Null, typeof(ITestMajorRecordGetter)),
         };
-        var toDeserialize = $"{{\"Direct\":\"Null\",\"Interface\":\"Null\"}}";
+        var toDeserialize = $"{{\"Direct\":\"Null<TestGame.TestMajorRecord>\",\"Interface\":\"Null<TestGame.TestMajorRecord>\"}}";
         JsonConvert.DeserializeObject<FormLinkInformationClass>(toDeserialize, settings)!
             .Direct
             .ShouldBe(target.Direct);
@@ -565,9 +586,24 @@ public void FormLinkInformationConverter_FormLink_Deserialize_Null()
     }
 
     [Fact]
-    public void FormLinkInformationConverter_FormLink_Deserialize()
+    public void FormLinkInformationConverter_FormLink_Serialize_Deserialize_Generic_Interface()
+    {
+        var settings = new JsonSerializerSettings();
+        settings.Converters.Add(new FormKeyJsonConverter());
+        var formKey = FormKey.Factory("123456:Mod.esm");
+        var target = new FormLinkInformationClass()
+        {
+            Interface = new FormLink<ITestMajorRecordGetter>(formKey),
+        };
+        var serialize = JsonConvert.SerializeObject(target, settings);
+        JsonConvert.DeserializeObject<FormLinkInformationClass>(serialize, settings)!
+            .Interface
+            .ShouldBe(target.Interface);
+    }
+    
+    [Fact]
+    public void FormLinkInformationConverter_FormLink_Deserialize_Null_BethesdaMajorRecord()
     {
-        Warmup.Init();
         var settings = new JsonSerializerSettings();
         settings.Converters.Add(new FormKeyJsonConverter());
         var target = new FormLinkInformationClass()
@@ -585,9 +621,8 @@ public void FormLinkInformationConverter_FormLink_Deserialize()
     }
 
     [Fact]
-    public void FormLinkInformationConverter_FormLink_Serialize_Null()
+    public void FormLinkInformationConverter_FormLink_Serialize_Null_BethesdaMajorRecord()
     {
-        Warmup.Init();
         var settings = new JsonSerializerSettings();
         settings.Converters.Add(new FormKeyJsonConverter());
         var target = new FormLinkInformationClass()
@@ -600,10 +635,30 @@ public void FormLinkInformationConverter_FormLink_Serialize_Null()
             .ShouldBe(toDeserialize);
     }
 
+    [Fact]
+    public void FormLinkInformationConverter_FormLink_Null_MajorRecord()
+    {
+        var settings = new JsonSerializerSettings();
+        settings.Converters.Add(new FormKeyJsonConverter());
+        var deserialized = new FormLinkInformationClass()
+        {
+            Interface = new FormLinkInformation(FormKey.Null, typeof(IMajorRecordGetter)),
+            Direct = new FormLinkInformation(FormKey.Null, typeof(IMajorRecordGetter)),
+        };
+        var serialized = $"{{\"Interface\":\"Null<MajorRecord>\",\"Direct\":\"Null<MajorRecord>\"}}";
+        JsonConvert.DeserializeObject<FormLinkInformationClass>(serialized, settings)!
+            .Direct
+            .ShouldBe(deserialized.Direct);
+        JsonConvert.DeserializeObject<FormLinkInformationClass>(serialized, settings)!
+            .Interface
+            .ShouldBe(deserialized.Interface);
+        JsonConvert.SerializeObject(deserialized, settings)
+            .ShouldBe(serialized);
+    }
+    
     [Fact]
     public void FormLinkInformationConverter_FormLink_Serialize()
     {
-        Warmup.Init();
         var settings = new JsonSerializerSettings();
         settings.Converters.Add(new FormKeyJsonConverter());
         var target = new FormLinkInformationClass()
@@ -619,7 +674,6 @@ public void FormLinkInformationConverter_FormLink_Serialize()
     [Fact]
     public void FormLinkInformationConverter_FormLink_Deserialize_Empty()
     {
-        Warmup.Init();
         var settings = new JsonSerializerSettings();
         settings.Converters.Add(new FormKeyJsonConverter());
         var target = new FormLinkInformationClass()

Mutagen.Bethesda.Core.UnitTests/Pex/BinaryExtensionTests.cs

@@ -76,11 +76,11 @@ private static void DoTest<T>(int streamCapacity, T expected, Action<BinaryWrite
     {
         using var ms = new MemoryStream(streamCapacity);
         using var bw = new BinaryWriter(ms);
-        using var br = new BinaryReadStream(ms, isLittleEndian: false);
 
         write(bw);
         ms.Position = 0;
 
+        using var br = new BinaryReadStream(ms, isLittleEndian: false);
         var actual = read(br);
         Assert.Equal(expected, actual);
         Assert.Equal(ms.Length, ms.Position);

Mutagen.Bethesda.Core.UnitTests/Placeholders/TestMajorRecord.cs

@@ -6,6 +6,7 @@
 using Mutagen.Bethesda.Plugins.Binary.Translations;
 using Mutagen.Bethesda.Plugins.Cache;
 using Mutagen.Bethesda.Plugins.Records;
+using Noggog;
 using Noggog.StructuredStrings;
 
 namespace Mutagen.Bethesda.UnitTests.Placeholders;
@@ -195,3 +196,31 @@ public IEnumerable<IAssetLinkGetter> EnumerateAssetLinks(AssetLinkQuery queryCat
         throw new NotImplementedException();
     }
 }
+internal class TestMajorRecord_Registration : ILoquiRegistration
+{
+    public static TestMajorRecord_Registration Instance { get; } = new();
+
+    public string GetNthName(ushort index) => throw new NotImplementedException();
+    public bool GetNthIsLoqui(ushort index) => throw new NotImplementedException();
+    public bool GetNthIsEnumerable(ushort index) => throw new NotImplementedException();
+    public bool GetNthIsSingleton(ushort index) => throw new NotImplementedException();
+    public bool IsNthDerivative(ushort index) => throw new NotImplementedException();
+    public Type GetNthType(ushort index) => throw new NotImplementedException();
+    public ushort? GetNameIndex(StringCaseAgnostic name) => throw new NotImplementedException();
+    public bool IsProtected(ushort index) => throw new NotImplementedException();
+    public ProtocolKey ProtocolKey { get; } = new("TestGame");
+    public ushort AdditionalFieldCount { get; }
+    public ushort FieldCount { get; }
+    public Type MaskType => null!;
+    public Type ErrorMaskType => null!;
+    public Type ClassType { get; } = typeof(TestMajorRecord);
+    public Type GetterType { get; } = typeof(ITestMajorRecordGetter);
+    public Type SetterType { get; } = typeof(ITestMajorRecord);
+    public Type? InternalGetterType { get; }
+    public Type? InternalSetterType { get; }
+    public string FullName => "Mutagen.Bethesda.TestGame.TestMajorRecord";
+    public string Name => "TestMajorRecord";
+    public string Namespace => "Mutagen.Bethesda";
+    public byte GenericCount { get; }
+    public Type? GenericRegistrationType { get; }
+}