[#99] Add --build-history option to analyze#109
Conversation
There was a problem hiding this comment.
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
BuildManifestHashmatching and “most recent wins” selection usingBuildReportSummary.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.
| public static List<string> FindBuildHashes(IEnumerable<string> files) | ||
| { | ||
| var fileList = files.ToList(); | ||
|
|
||
| var hashFiles = fileList | ||
| .Where(f => string.Equals(Path.GetFileName(f), HashFileName, StringComparison.OrdinalIgnoreCase)) | ||
| .ToList(); | ||
|
|
||
| if (hashFiles.Count == 0) | ||
| { | ||
| var contentDirectories = fileList | ||
| .Where(f => HasExtension(f, ".cf") || HasExtension(f, ".archive")) | ||
| .Select(f => Path.GetDirectoryName(Path.GetFullPath(f))) | ||
| .Distinct(StringComparer.OrdinalIgnoreCase); | ||
|
|
||
| hashFiles.AddRange(contentDirectories | ||
| .Select(dir => Path.Combine(dir, HashFileName)) | ||
| .Where(File.Exists)); | ||
| } | ||
|
|
||
| return hashFiles.Select(f => File.ReadAllText(f).Trim()).Distinct().ToList(); | ||
| } |
There was a problem hiding this comment.
Both values are machine-written lowercase hex from the same Unity build, so a case mismatch cannot occur between the files in practice. Still, normalizing at the read sites is cheap and removes the concern for hand-assembled inputs: 5ed3eec lowercases the hash when it is read (here and in TryReadBuildManifestHash), so every comparison stays a simple exact match. Empty hash files are left as-is: BuildManifestHash.txt is machine-written next to the content, so an empty one is a corrupt build and already surfaces as a clear 'no layout matches' error rather than something to silently skip.
| public static string LocateBuildFolder(string historyRoot, string buildHash) | ||
| { | ||
| var matches = Directory.EnumerateDirectories(historyRoot) | ||
| .Prepend(historyRoot) | ||
| .Where(dir => File.Exists(Path.Combine(dir, LayoutFileName))) | ||
| .Where(dir => TryReadBuildManifestHash(Path.Combine(dir, LayoutFileName)) == buildHash); | ||
|
|
||
| string selected = null; | ||
| var selectedTime = default(DateTime); |
There was a problem hiding this comment.
Addressed in 5ed3eec by normalizing to lowercase where the hashes are read (FindBuildHashes and TryReadBuildManifestHash) instead of at each comparison — both sides of this == are now guaranteed lowercase.
| // The hash match guarantees the layout describes exactly this build; a stale or | ||
| // unrelated layout would silently produce misleading results. | ||
| selected = layoutCandidates.FirstOrDefault(c => TryReadBuildManifestHash(c.FullPath) == buildHash); | ||
| selected = layoutCandidates.FirstOrDefault(c => BuildHistoryHelper.TryReadBuildManifestHash(c.FullPath) == buildHash); | ||
|
|
There was a problem hiding this comment.
Both sides of this comparison are lowercased at the read sites in BuildHistoryHelper as of 5ed3eec (BuildManifestHash.txt in FindBuildHashes, ContentLayout.json in TryReadBuildManifestHash), so the selection here is effectively case-insensitive without changing the comparison.
| if (candidate != selected) | ||
| { | ||
| Console.Error.WriteLine($"Ignoring \"{candidate.FullPath}\": its BuildManifestHash does not match the analyzed build."); | ||
| var reason = BuildHistoryHelper.TryReadBuildManifestHash(candidate.FullPath) == buildHash | ||
| ? "it duplicates the selected layout" | ||
| : "its BuildManifestHash does not match the analyzed build"; | ||
| Console.Error.WriteLine($"Ignoring \"{candidate.FullPath}\": {reason}."); |
There was a problem hiding this comment.
Same as above — covered by the read-site normalization in 5ed3eec, so a duplicate with different casing would now be reported as a duplicate.
Summary
Follow-up to #99. Analyzing a ContentDirectory build together with its
ContentLayout.jsonrequires finding the right folder insideLibrary/BuildHistory— the folder names are timestamp-derived and picking a stale layout by hand is easy to get wrong. Pointinganalyzeat the whole build history isn't a good answer either: a positional path means "analyze everything in here", which would import every.buildreportof every build in the history.This PR gives the lookup its own syntax instead of overloading positional paths:
analyzelocates the analyzed build's folder inside the build history (by matching theBuildManifestHashof eachContentLayout.jsonagainst the build'sBuildManifestHash.txt) and includes that folder'sContentLayout.jsonand.buildreportin the analysis. Positional paths keep their existing meaning unchanged.Changes
Behavior
--build-history <folder>option onanalyze. 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 byBuildStartedAtfrom each folder'sBuildReportSummary.json; the selected folder is printed.Code
Analyzer/Util/BuildHistoryHelper: pure file lookup (find the build hash from the input, locate the matching history folder, collect its importable files). TheBuildManifestHash.txtdiscovery and streamingBuildManifestHashreader moved here fromAnalyzerTool, shrinkingPrepareContentDirectoryInputsto just candidate selection and validation.UnityDataModels/BuildReportSummary.cs: the schema ofBuildReportSummary.json, a convenience type for reading it outside the Unity Editor (fields documented in the Editor's ScriptReference).Documentation
command-analyze.md:--build-historyin 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 howBuildReportSummary.jsonis used.Testing
dotnet test— full suite green (764 tests). NewAnalyzeBuildHistoryTests(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 viaBuildStartedAt(including a folder with a missing summary file), a duplicate positionally-passed layout, and hash discovery next to.archivefiles. 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