[#49] Allow analyze to accept multiple file or directory paths

The analyze command now takes a variadic positional argument: each path
may be a file or a directory. Directories are scanned (honoring
--search-pattern/--no-recurse); explicitly named files are analyzed
directly. This makes analyzing a single file simple and lets files from
multiple locations (e.g. a build output directory plus an external build
report) go into one database in a single invocation.

- AnalyzerTool.AnalyzeOptions.Paths replaces the single Path; CollectFiles
  expands inputs, dedups, and tracks per-input roots for relative display.
- Convert tests that used the awkward ". -p <file>" form to pass paths
  directly; add coverage for the directory-plus-external-file case.
- Document the new usage in command-analyze.md, analyzer.md and
  buildreport.md (including the Unity 6.6 build history workflow).

Fixes #49

Author: SkowronskiAndrew

Analyzer/AnalyzerTool.cs

@@ -23,7 +23,9 @@ public class AnalyzerTool
 
     public class AnalyzeOptions
     {
-        public string Path { get; init; }
+        // 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; }
@@ -59,17 +61,15 @@ public int Analyze(AnalyzeOptions options)
         var timer = new Stopwatch();
         timer.Start();
 
-        var files = Directory.GetFiles(
-            m_Options.Path,
-            m_Options.SearchPattern,
-            m_Options.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)
             {
@@ -79,15 +79,14 @@ public int Analyze(AnalyzeOptions options)
                     try
                     {
                         parser.Parse(file);
-                        ReportProgress(Path.GetRelativePath(m_Options.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(m_Options.Path, file);
                         Console.Error.WriteLine($"Failed to open: {relativePath}");
                         var hint = SerializedFileDetector.GetOpenFailureHint(e.FilePath);
                         if (hint != null)
@@ -98,7 +97,6 @@ public int Analyze(AnalyzeOptions options)
                     {
                         // Unexpected failure (SQL error, I/O error, bug, etc.) — print full details.
                         EraseProgressLine();
-                        var relativePath = Path.GetRelativePath(m_Options.Path, file);
                         Console.Error.WriteLine($"Failed to process: {relativePath}");
                         if (m_Options.Verbose)
                         {
@@ -115,7 +113,6 @@ public int Analyze(AnalyzeOptions options)
             {
                 if (m_Options.Verbose)
                 {
-                    var relativePath = Path.GetRelativePath(m_Options.Path, file);
                     Console.WriteLine();
                     Console.WriteLine($"Ignoring {relativePath}");
                 }
@@ -141,6 +138,40 @@ public int Analyze(AnalyzeOptions options)
         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)

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 contain
+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 |
 |------------|-------------|

UnityDataTool.Tests/BuildReportTests.cs

@@ -46,7 +46,7 @@ public async Task Analyze_BuildReport_ContainsExpected_ObjectInfo(
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "AssetBundle.buildreport" };
+        var args = new List<string> { "analyze", Path.Combine(m_TestDataFolder, "AssetBundle.buildreport") };
         if (skipReferences)
             args.Add("--skip-references");
 
@@ -159,7 +159,7 @@ public async Task Analyze_BuildReport_ContainsExpectedReferences(
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "AssetBundle.buildreport" };
+        var args = new List<string> { "analyze", Path.Combine(m_TestDataFolder, "AssetBundle.buildreport") };
         if (skipReferences)
             args.Add("--skip-references");
 
@@ -214,7 +214,7 @@ public async Task Analyze_BuildReport_AssetBundle_ContainsBuildReportData()
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "AssetBundle.buildreport" };
+        var args = new List<string> { "analyze", Path.Combine(m_TestDataFolder, "AssetBundle.buildreport") };
 
         Assert.AreEqual(0, await Program.Main(args.ToArray()));
         using var db = SQLTestHelper.OpenDatabase(databasePath);
@@ -246,7 +246,7 @@ public async Task Analyze_BuildReport_Player_ContainsBuildReportData()
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "Player.buildreport" };
+        var args = new List<string> { "analyze", Path.Combine(m_TestDataFolder, "Player.buildreport") };
 
         Assert.AreEqual(0, await Program.Main(args.ToArray()));
         using var db = SQLTestHelper.OpenDatabase(databasePath);
@@ -284,7 +284,7 @@ public async Task Analyze_BuildReport_AssetBundle_ContainsPackedAssetsData()
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "AssetBundle.buildreport" };
+        var args = new List<string> { "analyze", Path.Combine(m_TestDataFolder, "AssetBundle.buildreport") };
 
         Assert.AreEqual(0, await Program.Main(args.ToArray()));
         using var db = SQLTestHelper.OpenDatabase(databasePath);
@@ -344,13 +344,49 @@ public async Task Analyze_BuildReport_AssetBundle_ContainsPackedAssetsData()
             "Unexpected path in build_report_packed_assets_view");
     }
 
+    // The motivating case for issue #49: combine a scanned build-output directory with a build
+    // report file that lives in a separate location, all in a single analyze invocation.
+    [Test]
+    public async Task Analyze_DirectoryPlusExternalFile_BothIncluded()
+    {
+        var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
+
+        // Simulate a build output directory containing one report, with a second report kept elsewhere.
+        var buildOutputDir = Path.Combine(m_TestOutputFolder, "build_output");
+        Directory.CreateDirectory(buildOutputDir);
+        File.Copy(Path.Combine(m_TestDataFolder, "AssetBundle.buildreport"),
+            Path.Combine(buildOutputDir, "AssetBundle.buildreport"));
+
+        var args = new string[]
+        {
+            "analyze",
+            buildOutputDir,
+            Path.Combine(m_TestDataFolder, "Player.buildreport"),
+        };
+
+        Assert.AreEqual(0, await Program.Main(args));
+        using var db = SQLTestHelper.OpenDatabase(databasePath);
+
+        SQLTestHelper.AssertQueryInt(db, "SELECT COUNT(*) FROM build_reports", 2,
+            "Expected both the scanned directory's report and the external report");
+        SQLTestHelper.AssertQueryInt(db, "SELECT COUNT(*) FROM build_reports WHERE build_type = 'AssetBundle'", 1,
+            "Expected the AssetBundle report from the scanned directory");
+        SQLTestHelper.AssertQueryInt(db, "SELECT COUNT(*) FROM build_reports WHERE build_type = 'Player'", 1,
+            "Expected the Player report passed as an external file");
+    }
+
     [Test]
     public async Task Analyze_BuildReports_BothReports_ContainsBuildReportFilesData()
     {
         var databasePath = SQLTestHelper.GetDatabasePath(m_TestOutputFolder);
 
-        // Analyze multiple BuildReports into the same database
-        var args = new List<string> { "analyze", m_TestDataFolder, "-p", "*.buildreport" };
+        // Analyze multiple BuildReports into the same database by passing each file explicitly.
+        var args = new List<string>
+        {
+            "analyze",
+            Path.Combine(m_TestDataFolder, "AssetBundle.buildreport"),
+            Path.Combine(m_TestDataFolder, "Player.buildreport"),
+        };
 
         Assert.AreEqual(0, await Program.Main(args.ToArray()));
         using var db = SQLTestHelper.OpenDatabase(databasePath);

UnityDataTool.Tests/SerializedFileCommandTests.cs

@@ -605,8 +605,8 @@ public async Task ObjectList_CrossValidate_MatchesAnalyzeCommand()
     {
         // First, run analyze command to create database
         var databasePath = Path.Combine(m_TestOutputFolder, "test_analyze.db");
-        var analyzePath = m_TestDataFolder;
-        Assert.AreEqual(0, await Program.Main(new string[] { "analyze", analyzePath, "-o", databasePath, "-p", "level0" }));
+        var analyzePath = Path.Combine(m_TestDataFolder, "level0");
+        Assert.AreEqual(0, await Program.Main(new string[] { "analyze", analyzePath, "-o", databasePath }));
 
         // Now run serialized-file objectlist
         var path = Path.Combine(m_TestDataFolder, "level0");

UnityDataTool.Tests/UnityDataToolPlayerDataTests.cs

@@ -102,7 +102,7 @@ public async Task Analyze_PlayerDataNoTypeTree_ReportsFailureCorrectly()
             Console.SetError(swErr);
 
             // Analyze should return 0 even if files fail (non-zero would be a critical error)
-            Assert.AreEqual(0, await Program.Main(new string[] { "analyze", testDataFolder, "-p", "level0" }));
+            Assert.AreEqual(0, await Program.Main(new string[] { "analyze", Path.Combine(testDataFolder, "level0") }));
 
             var output = swOut.ToString() + swErr.ToString();