Implement DS ROM file system reading

README.md

@@ -15,7 +15,7 @@ The library supports .NET 5.0 and above on Linux, Window and MacOS.
 
 _Encryption, decryption or signature validation not supported yet._
 
-None yet.
+- DS cartridge filesystem: read
 
 ## Documentation
 

docs/docfx.json

@@ -10,41 +10,46 @@
           }
         ],
         "dest": "api",
-        "filter": "filter_config.yml"
+        "filter": "filter_config.yml",
+        "disableGitFeatures": false,
+        "disableDefaultFilter": false
       }
     ],
-    "build": {
-      "content": [
-        {
-          "files": [ "api/**.yml", "dev/**" ]
-        },
-        {
-          "files": [ "toc.yml", "index.md" ]
-        },
-        {
-          "files": [ "guides/**" ]
-        },
-        {
-          "files": ["README.md", "CONTRIBUTING.md"],
-          "src": "../"
-        }
-      ],
-      "resource": [
-        {
-          "files": ["images/**"]
-        }
-      ],
-      "dest": "_site",
-      "globalMetadataFiles": ["global_metadata.json"],
-      "fileMetadataFiles": [],
-      "template": [
-        "default",
-        "statictoc",
-        "default-widescreen"
-      ],
-      "postProcessors": [],
-      "markdownEngineName": "markdig",
-      "noLangKeyword": false,
-      "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ]
-    }
+  "build": {
+    "content": [
+      {
+        "files": [ "api/**.yml", "dev/**" ]
+      },
+      {
+        "files": [ "toc.yml", "index.md" ]
+      },
+      {
+        "files": [ "guides/**" ]
+      },
+      {
+        "files": [ "README.md", "CONTRIBUTING.md" ],
+        "src": "../"
+      }
+    ],
+    "resource": [
+      {
+        "files": [ "images/**" ]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadataFiles": [ "global_metadata.json" ],
+    "fileMetadataFiles": [],
+    "template": [
+      "default",
+      "statictoc",
+      "default-widescreen"
+    ],
+    "postProcessors": [],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false,
+    "xrefService": [ "https://xref.docs.microsoft.com/query?uid={uid}" ]
+  }
 }

src/.editorconfig

@@ -47,7 +47,7 @@ dotnet_style_prefer_inferred_tuple_names = true:suggestion
 dotnet_style_prefer_inferred_anonymous_type_member_names = true:suggestion
 dotnet_style_prefer_auto_properties = true:warning
 dotnet_style_prefer_conditional_expression_over_assignment = true:warning
-dotnet_style_prefer_conditional_expression_over_return = true:warning
+dotnet_style_prefer_conditional_expression_over_return = true:suggestion
 dotnet_style_prefer_compound_assignment = true:warning
 dotnet_style_prefer_simplified_interpolation = true:warning
 dotnet_style_prefer_simplified_boolean_expressions = true:warning
@@ -94,7 +94,7 @@ csharp_style_prefer_index_operator = true:warning
 csharp_style_prefer_range_operator = true:warning
 csharp_style_implicit_object_creation_when_type_is_apparent = true:suggestion
 csharp_style_unused_value_assignment_preference = discard_variable:warning
-csharp_style_unused_value_expression_statement_preference = discard_variable:warning
+csharp_style_unused_value_expression_statement_preference = discard_variable:suggestion
 
 ### Null-checking preferences
 csharp_style_throw_expression = true:warning
@@ -105,7 +105,7 @@ csharp_prefer_braces = when_multiline:error
 csharp_prefer_simple_using_statement = true:suggestion
 
 ### 'using' directive preferences
-csharp_using_directive_placement = inside_namespace:warning
+csharp_using_directive_placement = outside_namespace:warning
 
 ### Modifier preferences
 csharp_prefer_static_local_function = true:warning
@@ -169,6 +169,10 @@ dotnet_diagnostic.SA1101.severity = none # Do not force to prefix local calls wi
 dotnet_diagnostic.SA1500.severity = none # Allow inline braces
 dotnet_diagnostic.SA1503.severity = suggestion # Braces can be omitted (guards can)
 dotnet_diagnostic.SA1633.severity = none # No XML-format header in source files
+dotnet_diagnostic.SA1200.severity = none # Namespace outside
+
+### IDE
+dotnet_diagnostic.IDE0058.severity = suggestion # Expression value is never used
 
 ### SonarAnalyzer
 dotnet_diagnostic.S1135.severity = suggestion # It's almost inevitable to have TODO but add bug ID

src/Directory.Packages.props

@@ -1,17 +1,21 @@
 <Project>
     <!-- Centralize dependency management -->
     <ItemGroup>
-        <PackageVersion Include="Yarhl" Version="3.1.0" />
+        <PackageVersion Include="Yarhl" Version="3.1.1-preview.28" />
+        <PackageVersion Include="Texim" Version="0.1.0-preview.103" />
+        <PackageVersion Include="System.Data.HashFunction.CRC" Version="2.0.0" />
 
-        <PackageVersion Include="nunit" Version="3.13.1" />
+        <PackageVersion Include="YamlDotNet" Version="11.1.1" />
+        <PackageVersion Include="FluentAssertions" Version="5.10.3" />
+        <PackageVersion Include="nunit" Version="3.13.2" />
         <PackageVersion Include="NUnit3TestAdapter" Version="3.17.0" />
-        <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="16.9.1"/>
+        <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="16.9.4"/>
         <PackageVersion Include="coverlet.collector" Version="3.0.3" />
 
         <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="1.0.0" />
 
         <PackageVersion Include="StyleCop.Analyzers" Version="1.1.118" />
-        <PackageVersion Include="SonarAnalyzer.CSharp" Version="8.19.0.28253" />
+        <PackageVersion Include="SonarAnalyzer.CSharp" Version="8.23.0.32424" />
         <PackageVersion Include="Roslynator.Analyzers" Version="3.1.0" />
     </ItemGroup>
 </Project>

src/Ekona.Tests/Assertions/BinaryFormatAssertions.cs

@@ -0,0 +1,50 @@
+// Copyright(c) 2021 SceneGate
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+using FluentAssertions;
+using FluentAssertions.Primitives;
+using Yarhl.IO;
+
+namespace SceneGate.Ekona.Tests.Assertions
+{
+    public class BinaryFormatAssertions :
+        ReferenceTypeAssertions<BinaryFormat, BinaryFormatAssertions>
+    {
+        public BinaryFormatAssertions(BinaryFormat instance)
+            : base(instance)
+        {
+        }
+
+        protected override string Identifier => "binary";
+
+        [CustomAssertion]
+        public AndConstraint<BinaryFormatAssertions> MatchInfo(BinaryInfo info)
+        {
+            Subject.Stream.Should().MatchInfo(info);
+            return new AndConstraint<BinaryFormatAssertions>(this);
+        }
+
+        [CustomAssertion]
+        public AndConstraint<BinaryFormatAssertions> HaveSha256(string hash)
+        {
+            Subject.Stream.Should().HaveSha256(hash);
+            return new AndConstraint<BinaryFormatAssertions>(this);
+        }
+    }
+}

src/Ekona.Tests/Assertions/NodeAssertions.cs

@@ -0,0 +1,71 @@
+// Copyright(c) 2021 SceneGate
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+using FluentAssertions;
+using FluentAssertions.Execution;
+using FluentAssertions.Primitives;
+using Yarhl.FileSystem;
+
+namespace SceneGate.Ekona.Tests.Assertions
+{
+    public class NodeAssertions
+            : ReferenceTypeAssertions<Node, NodeAssertions>
+    {
+        public NodeAssertions(Node instance)
+            : base(instance)
+        {
+        }
+
+        protected override string Identifier => "node";
+
+        [CustomAssertion]
+        public AndConstraint<NodeAssertions> MatchInfo(NodeContainerInfo info)
+        {
+            Subject.Name.Should().Be(info.Name);
+            Subject.Format?.GetType().FullName.Should().Be(info.Format);
+
+            if (info.Tags != null) {
+                // YAML deserializer always gets the value as a string
+                foreach (var entry in info.Tags) {
+                    Subject.Tags.Should().ContainKey(entry.Key);
+                    entry.Value.Should().Be(Subject.Tags[entry.Key].ToString());
+                }
+            }
+
+            if (info.Stream != null) {
+                Subject.Stream.Should().MatchInfo(info.Stream);
+            }
+
+            int expectedCount = info.Children?.Count ?? 0;
+            if (info.CheckChildren) {
+                Subject.Children.Should().HaveCount(expectedCount);
+            }
+
+            for (int i = 0; i < expectedCount; i++) {
+                NodeContainerInfo expectedNode = info.Children[i];
+                using (new AssertionScope(expectedNode.Name)) {
+                    Subject.Children.Should().Contain(n => n.Name == expectedNode.Name);
+                    Subject.Children[expectedNode.Name].Should().MatchInfo(expectedNode);
+                }
+            }
+
+            return new AndConstraint<NodeAssertions>(this);
+        }
+    }
+}

src/Ekona.Tests/Assertions/StreamAssertions.cs

@@ -0,0 +1,77 @@
+// Copyright(c) 2021 SceneGate
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+using System;
+using System.IO;
+using System.Security.Cryptography;
+using FluentAssertions;
+using FluentAssertions.Execution;
+using FluentAssertions.Primitives;
+using Yarhl.IO;
+
+namespace SceneGate.Ekona.Tests.Assertions
+{
+    public class StreamAssertions :
+        ReferenceTypeAssertions<Stream, StreamAssertions>
+    {
+        public StreamAssertions(Stream instance)
+            : base(instance)
+        {
+        }
+
+        protected override string Identifier => "stream";
+
+        [CustomAssertion]
+        public AndConstraint<StreamAssertions> MatchInfo(BinaryInfo info)
+        {
+            Subject.Should()
+                .BeAssignableTo<DataStream>("We will compare its offset")
+                .Which
+                .Offset
+                .Should().Be(info.Offset);
+            Subject.Length.Should().Be(info.Length);
+
+            if (!string.IsNullOrEmpty(info.Sha256)) {
+                HaveSha256(info.Sha256);
+            }
+
+            return new AndConstraint<StreamAssertions>(this);
+        }
+
+        [CustomAssertion]
+        public AndConstraint<StreamAssertions> HaveSha256(string hash)
+        {
+            Subject.Position = 0;
+            using var sha256 = SHA256.Create();
+            sha256.ComputeHash(Subject);
+            string actualHash = BitConverter.ToString(sha256.Hash)
+                .Replace("-", string.Empty)
+                .ToLowerInvariant();
+
+            Execute.Assertion
+                .ForCondition(!string.IsNullOrEmpty(hash))
+                .FailWith("hash is empty")
+                .Then
+                .ForCondition(hash == actualHash)
+                .FailWith("Expected {context} to have SHA-256 {0} but was {1}", hash, actualHash);
+
+            return new AndConstraint<StreamAssertions>(this);
+        }
+    }
+}

src/Ekona.Tests/BinaryInfo.cs

@@ -0,0 +1,43 @@
+// Copyright(c) 2021 SceneGate
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+using System.IO;
+using YamlDotNet.Serialization;
+using YamlDotNet.Serialization.NamingConventions;
+
+namespace SceneGate.Ekona.Tests
+{
+    public class BinaryInfo
+    {
+        public long Offset { get; set; }
+
+        public long Length { get; set; }
+
+        public string Sha256 { get; set; }
+
+        public static BinaryInfo FromYaml(string path)
+        {
+            string yaml = File.ReadAllText(path);
+            return new DeserializerBuilder()
+                .WithNamingConvention(UnderscoredNamingConvention.Instance)
+                .Build()
+                .Deserialize<BinaryInfo>(yaml);
+        }
+    }
+}