[#49] Improve analyze file specification, CLI help and docs improvements (#76)

* Add some description for UnityDataTool --help
* AnalyzeTool - pass parameters through structure
* [#49] Allow analyze to accept multiple file or directory paths
* Clarify UnityFileSystemApi section in README

Author: SkowronskiAndrew

Analyzer/AnalyzerTool.cs

@@ -13,35 +13,41 @@ namespace UnityDataTools.Analyzer;
 
 public class AnalyzerTool
 {
-    bool m_Verbose = false;
+    AnalyzeOptions m_Options;
 
     public List<ISQLiteFileParser> parsers = new List<ISQLiteFileParser>()
     {
         new AddressablesBuildLayoutParser(),
         new SerializedFileParser(),
     };
 
-    public int Analyze(
-        string path,
-        string databaseName,
-        string searchPattern,
-        bool skipReferences,
-        bool skipCrc,
-        bool verbose,
-        bool noRecursion)
+    public class AnalyzeOptions
     {
-        m_Verbose = verbose;
+        // Each entry is a file or a directory. Directories are scanned using SearchPattern and
+        // NoRecursion; files are always included regardless of SearchPattern.
+        public IReadOnlyList<string> Paths { get; init; }
+        public string DatabaseName { get; init; }
+        public string SearchPattern { get; init; } = "*";
+        public bool SkipReferences { get; init; }
+        public bool SkipCrc { get; init; }
+        public bool Verbose { get; init; }
+        public bool NoRecursion { get; init; }
+    }
+
+    public int Analyze(AnalyzeOptions options)
+    {
+        m_Options = options;
 
-        using SQLiteWriter writer = new(databaseName);
+        using SQLiteWriter writer = new(m_Options.DatabaseName);
 
         try
         {
             writer.Begin();
             foreach (var parser in parsers)
             {
-                parser.Verbose = verbose;
-                parser.SkipReferences = skipReferences;
-                parser.SkipCrc = skipCrc;
+                parser.Verbose = m_Options.Verbose;
+                parser.SkipReferences = m_Options.SkipReferences;
+                parser.SkipCrc = m_Options.SkipCrc;
                 parser.Init(writer.Connection);
 
             }
@@ -55,17 +61,15 @@ public int Analyze(
         var timer = new Stopwatch();
         timer.Start();
 
-        var files = Directory.GetFiles(
-            path,
-            searchPattern,
-            noRecursion ? SearchOption.TopDirectoryOnly : SearchOption.AllDirectories);
+        var files = CollectFiles();
 
         int countFailures = 0;
         int countSuccess = 0;
         int countIgnored = 0;
         int i = 1;
-        foreach (var file in files)
+        foreach (var (file, displayRoot) in files)
         {
+            var relativePath = Path.GetRelativePath(displayRoot, file);
             bool foundParser = false;
             foreach (var parser in parsers)
             {
@@ -75,15 +79,14 @@ public int Analyze(
                     try
                     {
                         parser.Parse(file);
-                        ReportProgress(Path.GetRelativePath(path, file), i, files.Length);
+                        ReportProgress(relativePath, i, files.Count);
                         countSuccess++;
                     }
                     catch (SerializedFileOpenException e)
                     {
                         // Expected failure — the file content could not be parsed.
                         // Don't print a stack trace; it adds no value for this known failure mode.
                         EraseProgressLine();
-                        var relativePath = Path.GetRelativePath(path, file);
                         Console.Error.WriteLine($"Failed to open: {relativePath}");
                         var hint = SerializedFileDetector.GetOpenFailureHint(e.FilePath);
                         if (hint != null)
@@ -94,9 +97,8 @@ public int Analyze(
                     {
                         // Unexpected failure (SQL error, I/O error, bug, etc.) — print full details.
                         EraseProgressLine();
-                        var relativePath = Path.GetRelativePath(path, file);
                         Console.Error.WriteLine($"Failed to process: {relativePath}");
-                        if (m_Verbose)
+                        if (m_Options.Verbose)
                         {
                             Console.Error.WriteLine($"  Exception: {e.GetType().Name}: {e.Message}");
                             if (e.InnerException != null)
@@ -109,9 +111,8 @@ public int Analyze(
             }
             if (!foundParser)
             {
-                if (m_Verbose)
+                if (m_Options.Verbose)
                 {
-                    var relativePath = Path.GetRelativePath(path, file);
                     Console.WriteLine();
                     Console.WriteLine($"Ignoring {relativePath}");
                 }
@@ -137,12 +138,46 @@ public int Analyze(
         return 0;
     }
 
+    // Expands the input paths into the concrete files to analyze. Each result pairs the file with the
+    // root used to render its relative path in progress/error messages: the scanned directory for files
+    // found by scanning, or the file's own directory for explicitly-named files. Duplicates reached via
+    // more than one input are analyzed once.
+    List<(string FullPath, string DisplayRoot)> CollectFiles()
+    {
+        var searchOption = m_Options.NoRecursion ? SearchOption.TopDirectoryOnly : SearchOption.AllDirectories;
+        var collected = new List<(string FullPath, string DisplayRoot)>();
+        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+
+        foreach (var inputPath in m_Options.Paths)
+        {
+            if (Directory.Exists(inputPath))
+            {
+                foreach (var file in Directory.GetFiles(inputPath, m_Options.SearchPattern, searchOption))
+                {
+                    if (seen.Add(Path.GetFullPath(file)))
+                        collected.Add((file, inputPath));
+                }
+            }
+            else if (File.Exists(inputPath))
+            {
+                if (seen.Add(Path.GetFullPath(inputPath)))
+                    collected.Add((inputPath, Path.GetDirectoryName(Path.GetFullPath(inputPath))));
+            }
+            else
+            {
+                Console.Error.WriteLine($"Warning: path not found, skipping: {inputPath}");
+            }
+        }
+
+        return collected;
+    }
+
     int m_LastProgressMessageLength = 0;
 
     void ReportProgress(string relativePath, int fileIndex, int cntFiles)
     {
         var message = $"Processing {fileIndex * 100 / cntFiles}% ({fileIndex}/{cntFiles}) {relativePath}";
-        if (!m_Verbose)
+        if (!m_Options.Verbose)
         {
             EraseProgressLine();
             Console.Write($"\r{message}");
@@ -158,7 +193,7 @@ void ReportProgress(string relativePath, int fileIndex, int cntFiles)
 
     void EraseProgressLine()
     {
-        if (!m_Verbose)
+        if (!m_Options.Verbose)
             Console.Write($"\r{new string(' ', m_LastProgressMessageLength)}\r");
         else
             Console.WriteLine();

Documentation/analyzer.md

@@ -188,9 +188,10 @@ The [AnalyzerTool](../Analyzer/AnalyzerTool.cs) class is the API entry point. Th
 Analyze. It is currently hard coded to write using the [SQLiteWriter](../Analyzer/SQLite/SQLiteWriter.cs),
 but this approach could be extended to add support for other outputs.
 
-Calling this method will recursively process the files matching the search pattern in the provided
-path. It will add a row in the 'objects' table for each serialized object. This table contain basic
-information such as the size and the name of the object (if it has one).
+Calling this method processes the provided paths, which can be individual files or directories.
+Directories are scanned recursively for files matching the search pattern (unless recursion is
+disabled). It will add a row in the 'objects' table for each serialized object. This table contains
+basic information such as the size and the name of the object (if it has one).
 
 ## Extending the Library
 

Documentation/buildreport.md

@@ -49,7 +49,13 @@ SELECT build_time_asset_path from build_report_source_assets WHERE build_time_as
 
 ## Cross-Referencing with Build Output
 
-For comprehensive analysis, run `analyze` on both the build output **and** the matching build report file. Use a clean build to ensure PackedAssets information is fully populated. You may need to copy the build report into the build output directory so both are found by `analyze`.
+For comprehensive analysis, run `analyze` on both the build output **and** the matching build report file. Use a clean build to ensure PackedAssets information is fully populated.
+
+`analyze` accepts multiple path arguments, each of which can be a file or a directory, so you can pass the build output directory together with the build report path (or the directory containing it) in a single command:
+
+```bash
+UnityDataTool analyze /path/to/build/output /path/to/Library/LastBuild.buildreport
+```
 
 PackedAssets data provides source asset information for each object that isn't available when analyzing only the build output. Objects are listed in the same order as they appear in the output SerializedFile, .resS, or .resource file.
 
@@ -64,11 +70,33 @@ PackedAssets data provides source asset information for each object that isn't a
 
 ## Working with Multiple Build Reports
 
-Multiple build reports can be imported into the same database if their filenames differ. This enables:
+Multiple build reports can be imported into the same database if their filenames differ. Pass each report (and any build output directories) as separate path arguments to a single `analyze` command. This enables:
 - Comprehensive build history tracking
 - Cross-build comparisons
 - Identifying duplicated data between Player and AssetBundle builds
 
+### Prior to Unity 6.6
+
+Each build overwrites `Library/LastBuild.buildreport`. To compare builds, manually collect the report after each build, rename the copies so the filenames are unique (the analyzer keys serialized files by filename), then pass them to `analyze`:
+
+```bash
+UnityDataTool analyze build1.buildreport build2.buildreport
+```
+
+### Unity 6.6 and later
+
+Player and content directory builds record a structured [build history](https://docs.unity3d.com/6000.6/Documentation/ScriptReference/Build.BuildHistory.html) (default location `Library/BuildHistory`). Unity assigns each build its own directory and gives every build report a unique GUID-based filename, so there is no need to copy or rename reports to compare them. Run `analyze` on the entire build history folder, or on specific build report directories:
+
+```bash
+# Analyze every build in the history
+UnityDataTool analyze Library/BuildHistory
+
+# Analyze two specific builds
+UnityDataTool analyze Library/BuildHistory/20260504-153912Z-2dd7642e Library/BuildHistory/20260504-153855Z-7aff42f4
+```
+
+AssetBundle builds are not tracked in the build history; they still write only to `Library/LastBuild.buildreport`.
+
 See the schema sections below for guidance on writing queries that handle multiple build reports correctly.
 
 ## Alternatives

Documentation/command-analyze.md

@@ -5,27 +5,41 @@ The `analyze` command extracts information from Unity Archives (e.g. AssetBundle
 ## Quick Reference
 
 ```
-UnityDataTool analyze <path> [options]
+UnityDataTool analyze <paths>... [options]
 ```
 
 | Option | Description | Default |
 |--------|-------------|---------|
-| `<path>` | Path to folder containing files to analyze | *(required)* |
+| `<paths>...` | One or more files or directories to analyze. Directories are scanned; files are analyzed directly. | *(required)* |
 | `-o, --output-file <file>` | Output database filename | `database.db` |
-| `-p, --search-pattern <pattern>` | File search pattern (`*` and `?` supported) | `*` |
+| `-p, --search-pattern <pattern>` | File search pattern applied when scanning directories (`*` and `?` supported) | `*` |
 | `-s, --skip-references` | Do not extract references (smaller DB, no `refs` table). CRC is still computed. | `false` |
 | `--skip-crc` | Skip the CRC32 checksum calculation (faster; `objects.crc32` will be 0) | `false` |
 | `-v, --verbose` | Show more information during analysis | `false` |
-| `--no-recurse` | Do not recurse into sub-directories | `false` |
+| `--no-recurse` | Do not recurse into sub-directories when scanning directories | `false` |
 | `-d, --typetree-data <file>` | Load an external TypeTree data file before processing (Unity 6.5+) | — |
 
+There is no way to append to an existing database, so every file you want in the results must be
+included in a single `analyze` invocation. Pass multiple paths to combine files from more than one
+location into the same database.
+
 ## Examples
 
 Analyze all files in a directory:
 ```bash
 UnityDataTool analyze /path/to/asset/bundles
 ```
 
+Analyze a single file (no need for `.` plus `-p`):
+```bash
+UnityDataTool analyze /path/to/asset/bundles/my.bundle
+```
+
+Combine a build output directory with a build report file kept in a separate location:
+```bash
+UnityDataTool analyze /path/to/build/output /path/to/Library/LastBuild.buildreport
+```
+
 Analyze only `.bundle` files and specify a custom database name:
 ```bash
 UnityDataTool analyze /path/to/asset/bundles -o my_database.db -p "*.bundle"
@@ -42,7 +56,9 @@ See also [Analyze Examples](../../Documentation/analyze-examples.md).
 
 ## What Can Be Analyzed
 
-The analyze command works with the following types of directories:
+Each path may be an individual file or a directory. Directories are scanned (honoring
+`--search-pattern` and `--no-recurse`); individually-named files are always analyzed. The analyze
+command works with the following types of input:
 
 | Input Type | Description |
 |------------|-------------|

README.md

@@ -40,17 +40,15 @@ Refer to the [commit history](https://github.com/Unity-Technologies/UnityDataToo
 
 ## Getting UnityFileSystemApi
 
-UnityFileSystemApi is distributed in the Tools folder of the Unity Editor (from version 2022.1.0a14). The UnityDataTools repository includes a Windows, Mac, and Linux copy of the library in the `UnityFileSystem/` directory. 
+UnityDataTool uses the native `UnityFileSystemApi` library to read Unity Archives and SerializedFiles. **Normally you don't need to do anything with this library.** The repository already includes a recent Windows, Mac, and Linux copy in the [`UnityFileSystem/`](https://github.com/Unity-Technologies/UnityDataTools/tree/main/UnityFileSystem) directory, and using that bundled copy is the recommended way to run the tool.
 
-The library is backward compatible and can read data files from most Unity versions, so typically the version that is provided with UnityDataTools can be used "as is".
+The library is backward compatible but not forward compatible: a given version can read content from the same or older Unity versions, but may be unable to read content produced by a newer Unity Editor than the library itself. The bundled copy is updated periodically as Unity evolves, so in practice it can read content from just about any Unity version.
 
-To analyze data using the library from a specific version of the Unity Editor, copy the appropriate UnityFileSystemApi file from your Unity Editor installation (`{UnityEditor}/Data/Tools/`) to `UnityDataTool/UnityFileSystem/` prior to building:
+`UnityFileSystemApi` is also distributed in the `Data/Tools/` folder of the Unity Editor (for all versions since 2022.1.0a14). In the rare case that you need to read content from a Unity version newer than the bundled library, copy the matching file from your Unity Editor installation (`{UnityEditor}/Data/Tools/`) into the `UnityFileSystem/` directory before building:
 
-The file name is as follows:
-
-- Windows: `UnityFileSystemApi.dll`
-- Mac: `UnityFileSystemApi.dylib`
-- Linux: `UnityFileSystemApi.so`
+- Windows: [`UnityFileSystemApi.dll`](https://github.com/Unity-Technologies/UnityDataTools/blob/main/UnityFileSystem/UnityFileSystemApi.dll)
+- Mac: [`UnityFileSystemApi.dylib`](https://github.com/Unity-Technologies/UnityDataTools/blob/main/UnityFileSystem/UnityFileSystemApi.dylib)
+- Linux: [`UnityFileSystemApi.so`](https://github.com/Unity-Technologies/UnityDataTools/blob/main/UnityFileSystem/UnityFileSystemApi.so)
 
 ## How to Build