Adding "header" subcommand for serialized file

Author: SkowronskiAndrew

Documentation/command-serialized-file.md

@@ -8,6 +8,7 @@ The `serialized-file` command (alias: `sf`) provides utilities for quickly inspe
 |-------------|-------------|
 | [`externalrefs`](#externalrefs) | List external file references |
 | [`objectlist`](#objectlist) | List all objects in the file |
+| [`header`](#header) | Show SerializedFile header information |
 
 ---
 
@@ -128,13 +129,79 @@ UnityDataTool serialized-file objectlist level0 --format json
 
 ---
 
+## header
+
+Shows the SerializedFile header information. This is useful for testing whether a file is a valid SerializedFile and for inspecting the version and structure.
+
+### Quick Reference
+
+```
+UnityDataTool serialized-file header <filename> [options]
+UnityDataTool sf header <filename> [options]
+```
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `<filename>` | Path to the SerializedFile | *(required)* |
+| `-f, --format <format>` | Output format: `Text` or `Json` | `Text` |
+
+### Example - Text Output
+
+```bash
+UnityDataTool sf header sharedassets0.assets
+```
+
+**Output:**
+```
+Version              22
+Format               Modern (64-bit)
+File Size            1,234,567 bytes
+Metadata Size        45,678 bytes
+Data Offset          45,728
+Endianness           Little Endian
+```
+
+### Example - JSON Output
+
+```bash
+UnityDataTool serialized-file header level0 --format json
+```
+
+**Output:**
+```json
+{
+  "version": 22,
+  "format": "Modern (64-bit)",
+  "fileSize": 31988,
+  "metadataSize": 24580,
+  "dataOffset": 24640,
+  "endianness": "Big Endian"
+}
+```
+
+### Header Fields
+
+| Field | Description |
+|-------|-------------|
+| **Version** | SerializedFile format version. Modern Unity (2019+) uses version 22+. |
+| **Format** | Header format type: "Legacy (32-bit)" for versions < 22, or "Modern (64-bit)" for versions ≥ 22. Modern format supports files larger than 4GB. |
+| **File Size** | Total size of the SerializedFile in bytes. Padding might make the actual file size slightly larger. |
+| **Metadata Size** | Size of the metadata section containing type information and object indices. |
+| **Data Offset** | Byte offset where the object data section begins in the file. |
+| **Endianness** | Byte order of the file: "Little Endian" (x86, most platforms) or "Big Endian" (older console platforms). |
+
+---
+
 ## Use Cases
 
 ### Quick File Inspection
 
 Use `serialized-file` when you need quick information about a SerializedFile without generating a full SQLite database:
 
 ```bash
+# Check file format and version
+UnityDataTool sf header level0
+
 # Check what objects are in a file
 UnityDataTool sf objectlist sharedassets0.assets
 

UnityDataTool.Tests/SerializedFileCommandTests.cs

@@ -295,6 +295,123 @@ public async Task ObjectList_SharedAssets_ContainsExpectedTypes()
 
     #endregion
 
+    #region Header Tests
+
+    [Test]
+    public async Task Header_TextFormat_OutputsCorrectly()
+    {
+        var path = Path.Combine(TestContext.CurrentContext.TestDirectory, "Data", "PlayerNoTypeTree", "sharedassets0.assets");
+        using var sw = new StringWriter();
+        var currentOut = Console.Out;
+        try
+        {
+            Console.SetOut(sw);
+
+            Assert.AreEqual(0, await Program.Main(new string[] { "serialized-file", "header", path }));
+
+            var output = sw.ToString();
+            var lines = output.Split(new[] { '\r', '\n' }, StringSplitOptions.RemoveEmptyEntries);
+
+            // Should have header information lines
+            Assert.Greater(lines.Length, 0, "Expected header information");
+
+            // Check for expected fields
+            StringAssert.Contains("Version", output);
+            StringAssert.Contains("Format", output);
+            StringAssert.Contains("File Size", output);
+            StringAssert.Contains("Metadata Size", output);
+            StringAssert.Contains("Data Offset", output);
+            StringAssert.Contains("Endianness", output);
+        }
+        finally
+        {
+            Console.SetOut(currentOut);
+        }
+    }
+
+    [Test]
+    public async Task Header_JsonFormat_OutputsValidJson()
+    {
+        var path = Path.Combine(TestContext.CurrentContext.TestDirectory, "Data", "BuildReports", "Player.buildreport");
+        using var sw = new StringWriter();
+        var currentOut = Console.Out;
+        try
+        {
+            Console.SetOut(sw);
+
+            Assert.AreEqual(0, await Program.Main(new string[] { "serialized-file", "header", path, "-f", "json" }));
+
+            var output = sw.ToString();
+
+            // Parse JSON to verify it's valid
+            var jsonDoc = JsonDocument.Parse(output);
+            var root = jsonDoc.RootElement;
+
+            // Verify all expected properties are present
+            Assert.IsTrue(root.TryGetProperty("version", out _));
+            Assert.IsTrue(root.TryGetProperty("format", out _));
+            Assert.IsTrue(root.TryGetProperty("fileSize", out _));
+            Assert.IsTrue(root.TryGetProperty("metadataSize", out _));
+            Assert.IsTrue(root.TryGetProperty("dataOffset", out _));
+            Assert.IsTrue(root.TryGetProperty("endianness", out _));
+
+            // Verify version is a number
+            var version = root.GetProperty("version").GetUInt32();
+            Assert.Greater(version, 0u, "Version should be greater than 0");
+
+            // Verify format is a valid string
+            var format = root.GetProperty("format").GetString();
+            Assert.IsTrue(format == "Legacy (32-bit)" || format == "Modern (64-bit)",
+                $"Format should be either Legacy or Modern, got: {format}");
+        }
+        finally
+        {
+            Console.SetOut(currentOut);
+        }
+    }
+
+    [Test]
+    public async Task Header_InvalidFile_ReturnsError()
+    {
+        var path = Path.Combine(m_TestDataFolder, "README.md");
+
+        var result = await Program.Main(new string[] { "serialized-file", "header", path });
+        Assert.AreNotEqual(0, result, "Should return error code for invalid file");
+    }
+
+    [Test]
+    public async Task Header_ArchiveFile_ReturnsError()
+    {
+        var legacyDir = Path.Combine(TestContext.CurrentContext.TestDirectory, "Data", "LegacyFormats");
+        var archivePath = Path.Combine(legacyDir, "alienprefab");
+
+        if (!File.Exists(archivePath))
+        {
+            Assert.Ignore("alienprefab test file not found");
+            return;
+        }
+
+        using var sw = new StringWriter();
+        var currentErr = Console.Error;
+        try
+        {
+            Console.SetError(sw);
+
+            var result = await Program.Main(new string[] { "serialized-file", "header", archivePath });
+
+            Assert.AreNotEqual(0, result, "Should return error code for archive file");
+
+            var errorOutput = sw.ToString();
+            StringAssert.Contains("Unity Archive", errorOutput, "Error message should mention Unity Archive");
+        }
+        finally
+        {
+            Console.SetError(currentErr);
+        }
+    }
+
+    #endregion
+
     #region Cross-Validation with Analyze Command
 
     [Test]

UnityDataTool/Program.cs

@@ -154,10 +154,21 @@ public static async Task<int> Main(string[] args)
                 (FileInfo fi, OutputFormat f) => Task.FromResult(SerializedFileCommands.HandleObjectList(fi, f)),
                 pathArg, fOpt);
 
+            var headerCommand = new Command("header", "Show SerializedFile header information.")
+            {
+                pathArg,
+                fOpt,
+            };
+
+            headerCommand.SetHandler(
+                (FileInfo fi, OutputFormat f) => Task.FromResult(SerializedFileCommands.HandleHeader(fi, f)),
+                pathArg, fOpt);
+
             var serializedFileCommand = new Command("serialized-file", "Inspect a SerializedFile (scene, assets, etc.).")
             {
                 externalRefsCommand,
                 objectListCommand,
+                headerCommand,
             };
 
             serializedFileCommand.AddAlias("sf");

UnityDataTool/SerializedFileCommands.cs

@@ -30,6 +30,47 @@ public static int HandleObjectList(FileInfo filename, OutputFormat format)
         });
     }
 
+    public static int HandleHeader(FileInfo filename, OutputFormat format)
+    {
+        string filePath = filename.FullName;
+
+        // Check if file exists
+        if (!File.Exists(filePath))
+        {
+            Console.Error.WriteLine($"Error: File not found: {filePath}");
+            return 1;
+        }
+
+        // Detect if it's an archive (not supported for header command)
+        if (ArchiveDetector.IsUnityArchive(filePath))
+        {
+            Console.Error.WriteLine($"Error: The file is an AssetBundle or other Unity Archive, not a SerializedFile.");
+            Console.Error.WriteLine($"File: {filePath}");
+            Console.Error.WriteLine();
+            Console.Error.WriteLine("Unity Archives do not have a SerializedFile header.");
+            Console.Error.WriteLine("Extract the archive first to access SerializedFiles inside:");
+            Console.Error.WriteLine($"  UnityDataTool archive extract \"{filePath}\" -o <output-directory>");
+            return 1;
+        }
+
+        // Try to detect the SerializedFile header
+        bool isSerializedFile = SerializedFileDetector.TryDetectSerializedFile(filePath, out var fileInfo);
+        if (!isSerializedFile || fileInfo == null)
+        {
+            Console.Error.WriteLine($"Error: The file does not appear to be a valid Unity SerializedFile.");
+            Console.Error.WriteLine($"File: {filePath}");
+            return 1;
+        }
+
+        // Output the header information
+        if (format == OutputFormat.Json)
+            OutputHeaderJson(fileInfo);
+        else
+            OutputHeaderText(fileInfo);
+
+        return 0;
+    }
+
     /// <summary>
     /// Opens a SerializedFile and processes it with the given action.
     /// Provides helpful error messages if the file is not a valid SerializedFile.
@@ -169,5 +210,31 @@ private static string GetTypeName(SerializedFile sf, ObjectInfo obj)
             return TypeIdRegistry.GetTypeName(obj.TypeId);
         }
     }
+
+    private static void OutputHeaderText(SerializedFileInfo info)
+    {
+        Console.WriteLine($"{"Version",-20} {info.Version}");
+        Console.WriteLine($"{"Format",-20} {(info.IsLegacyFormat ? "Legacy (32-bit)" : "Modern (64-bit)")}");
+        Console.WriteLine($"{"File Size",-20} {info.FileSize:N0} bytes");
+        Console.WriteLine($"{"Metadata Size",-20} {info.MetadataSize:N0} bytes");
+        Console.WriteLine($"{"Data Offset",-20} {info.DataOffset:N0}");
+        Console.WriteLine($"{"Endianness",-20} {(info.Endianness == 0 ? "Little Endian" : "Big Endian")}");
+    }
+
+    private static void OutputHeaderJson(SerializedFileInfo info)
+    {
+        var jsonObject = new
+        {
+            version = info.Version,
+            format = info.IsLegacyFormat ? "Legacy (32-bit)" : "Modern (64-bit)",
+            fileSize = info.FileSize,
+            metadataSize = info.MetadataSize,
+            dataOffset = info.DataOffset,
+            endianness = info.Endianness == 0 ? "Little Endian" : "Big Endian"
+        };
+
+        var json = JsonSerializer.Serialize(jsonObject, new JsonSerializerOptions { WriteIndented = true });
+        Console.WriteLine(json);
+    }
 }