[#99] Add --build-history option to analyze

[SkowronskiAndrew]

Summary

Follow-up to #99. Analyzing a ContentDirectory build together with its ContentLayout.json requires finding the right folder inside Library/BuildHistory — the folder names are timestamp-derived and picking a stale layout by hand is easy to get wrong. Pointing analyze at the whole build history isn't a good answer either: a positional path means "analyze everything in here", which would import every .buildreport of every build in the history.

This PR gives the lookup its own syntax instead of overloading positional paths:

UnityDataTool analyze <build-output> --build-history Library/BuildHistory

analyze locates the analyzed build's folder inside the build history (by matching the BuildManifestHash of each ContentLayout.json against the build's BuildManifestHash.txt) and includes that folder's ContentLayout.json and .buildreport in the analysis. Positional paths keep their existing meaning unchanged.

Changes

Behavior

• New --build-history <folder> option on analyze. The lookup checks the given folder and its direct children only (no recursion — a build history is flat, and this keeps the scan bounded if a large unrelated folder is passed). When several folders match the hash (rebuilds of identical content), the most recent build wins, compared by BuildStartedAt from each folder's BuildReportSummary.json; the selected folder is printed.
• Clear errors when nothing in the history matches the analyzed build, or when the input contains no ContentDirectory build to match against (Player builds have no comparable identifier yet).
• Files added from the history are validated by the same code path as manually passed layouts, so all existing input combinations and their error cases behave as before. One message fix: a redundant copy of the already-selected layout is now reported as a duplicate rather than a hash mismatch.

Code

• New Analyzer/Util/BuildHistoryHelper: pure file lookup (find the build hash from the input, locate the matching history folder, collect its importable files). The BuildManifestHash.txt discovery and streaming BuildManifestHash reader moved here from AnalyzerTool, shrinking PrepareContentDirectoryInputs to just candidate selection and validation.
• New UnityDataModels/BuildReportSummary.cs: the schema of BuildReportSummary.json, a convenience type for reading it outside the Unity Editor (fields documented in the Editor's ScriptReference).

Documentation

• command-analyze.md: --build-history in the options table and examples; the ContentDirectory section now recommends it and covers the new input combinations.
• contentdirectory-format.md: the "how to analyze" instructions use the new form; note on how BuildReportSummary.json is used.

Testing

dotnet test — full suite green (764 tests). New AnalyzeBuildHistoryTests (8 tests) cover the happy path (layout imported, build report imported, references resolved), pointing at a build folder directly, no-match and no-ContentDirectory errors, most-recent selection via BuildStartedAt (including a folder with a missing summary file), a duplicate positionally-passed layout, and hash discovery next to .archive files. Build history folders are assembled per test from the existing LeadingEdge reference build fixtures; all pre-existing ContentLayout tests pass unmodified.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds first-class support for analyzing a ContentDirectory build together with its matching Library/BuildHistory entry, avoiding accidental import of stale layouts or unrelated build reports while keeping positional path behavior unchanged.

Changes:

• Added analyze --build-history <folder> CLI option and plumbed it into analyzer options.
• Implemented build-history lookup via BuildManifestHash matching and “most recent wins” selection using BuildReportSummary.json.
• Added a new data model, updated docs, and introduced a dedicated test suite for the new behavior.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
UnityDataTool/Program.cs	Adds --build-history option and passes it through to the analyzer.
Analyzer/AnalyzerTool.cs	Integrates build history lookup into ContentDirectory input preparation and de-duplication messaging.
Analyzer/Util/BuildHistoryHelper.cs	New helper for hash discovery, build folder selection, and collecting importable files.
UnityDataModels/BuildReportSummary.cs	Adds a JSON model used to read BuildReportSummary.json build start time.
UnityDataTool.Tests/AnalyzeBuildHistoryTests.cs	Adds coverage for happy path, failure modes, and most-recent selection logic.
Documentation/contentdirectory-format.md	Updates recommended workflow to use --build-history and explains summary usage.
Documentation/command-analyze.md	Documents the new option and ContentDirectory input combinations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.