Skip to content

[#72] Add find-refs test coverage and fix its database/null-ref bugs#79

Merged
SkowronskiAndrew merged 3 commits into
mainfrom
fix-find-ref
Jul 2, 2026
Merged

[#72] Add find-refs test coverage and fix its database/null-ref bugs#79
SkowronskiAndrew merged 3 commits into
mainfrom
fix-find-ref

Conversation

@SkowronskiAndrew

@SkowronskiAndrew SkowronskiAndrew commented Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Summary

This branch introduces a second Unity reference project used to generate deterministic test data, adds the first tests that run against that build output, and fixes the broken find-refs command (the original motivation, issue #72) while adding thorough test coverage for it.

Changes

Fix find-refs (issue #72 + a second bug)

find-refs had no automated tests and two bugs that broke it against any database produced by the current analyze:

  • Issue find-refs fails to open database: "Connection string keyword 'version' is not supported" #72 — database fails to open. The connection string was hand-written using the legacy System.Data.SQLite Version=3 keyword, which Microsoft.Data.Sqlite rejects (Connection string keyword 'version' is not supported). It is now built with SqliteConnectionStringBuilder, matching SQLiteWriter. The same broken string in ExpectedDataGenerator was fixed too.
  • Second bug — crash on ScriptableObject chains. A ScriptableObject is a MonoBehaviour whose m_GameObject PPtr is 0, so its game_object column holds a non-null id that matches no row; the game_object/script correlated subqueries then return NULL and GetString threw InvalidOperationException. Those reads are now null-checked. This broke find-refs for essentially any ScriptableObject reference chain.

--stdout for find-refs

Added a --stdout option (mutually exclusive with -o/--output-file), mirroring dump, so chains can be written to the console. command-find-refs.md documents the new option and clarifies the traversal behavior: find-refs walks up the reference graph and stops at the first asset it reaches, so chains end at the immediate containing asset rather than the ultimate root.

New find-refs tests

UnityDataTool.Tests/FindRefsTests.cs runs analyze on the LeadingEdge AssetBundle build in setup and covers:

  • Regression for issue find-refs fails to open database: "Connection string keyword 'version' is not supported" #72 (opens the DB without the connection-string error).
  • AudioClip shared by two assets → two chains; referenced once → one chain.
  • Name-only lookup matches both the MonoBehaviour and its MonoScript; adding a type narrows to one (disambiguation).
  • ScriptableObject chains render [Script = ...] without crashing (regression for the second bug).
  • Reaching AssetBundleRoot from a leaf asset, and confirming a target search stops at the leaf asset (documents the stop-at-first-asset traversal).
  • Lookup by object id, --find-all (produces identical chains to the default for this data), non-existent object, empty refs table (--skip-references), and the --stdout/-o validator.
  • Direct refs/object_view queries validating the underlying reference counts.

Second reference Unity project (LeadingEdge) and reference build data

  • Renamed the existing test project to Baseline (stable LTS versions) and added LeadingEdge, which tracks the newest Unity version so newer build features (Content Directory builds, serialized Dictionary<,>, Loadable`) can be tested. Editor scripts generate ScriptableObjects with well-known relationships between assets and AudioClips and run both AssetBundle and Content Directory builds.
  • Checked in the resulting reference build output under TestCommon/Data/LeadingEdgeBuilds (AssetBundles, Content Directory, and build reports), used by the new tests.
  • Added AGENTS.md/CLAUDE.md documentation for the projects and test-data folders.

First test using the new build output (dump)

DumpTests gained a test that dumps the SerializationDemo ScriptableObject from the LeadingEdge AssetBundle build and confirms the serialized field layout and values across the core numeric types, the string, the [SerializeReference] managed reference, and the int array.

Testing

dotnet test UnityDataTool.Tests — 231 passing, 0 failing.

@SkowronskiAndrew
Introduce second UnityProject
fad6cc3 
Rename UnityFileSystemTestData and introduce a LeadingEdge project for testing Content Directory builds and other newer features that require Unity >=6.6.
Add AGENTS.md explaining the relationship between these projects and the referenced files checked in to TestCommon
@SkowronskiAndrew
Dump command tested with core numeric field types and other serializa…
4d0409b 
…tion primitives
@SkowronskiAndrew SkowronskiAndrew requested a review from Copilot July 2, 2026 12:56
Copilot AI reviewed Jul 2, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes the find-refs CLI command to work against current analyze-produced databases (issue #72 and a ScriptableObject null-read crash), adds --stdout output support, and introduces deterministic Unity build outputs plus NUnit coverage to prevent regressions.

Changes:

  • Fix find-refs database opening and NULL handling in correlated subqueries; add --stdout output mode and CLI validation.
  • Add comprehensive find-refs regression/behavior tests (plus one new dump test) using checked-in LeadingEdge AssetBundle build output.
  • Introduce/rename Unity reference projects (Baseline, LeadingEdge) and check in corresponding reference build/test-data + documentation.

Reviewed changes

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

Show a summary per file
File Description
UnityProjects/LeadingEdge/CLAUDE.md Points to the project’s agent guidance.
UnityProjects/LeadingEdge/Assets/Scripts/SerializationDemo.cs.meta Unity metadata for SerializationDemo.
UnityProjects/LeadingEdge/Assets/Scripts/SerializationDemo.cs New ScriptableObject used to exercise serialization for dump testing.
UnityProjects/LeadingEdge/Assets/Scripts/LoadableAudioClipReference.cs.meta Unity metadata for LoadableAudioClipReference.
UnityProjects/LeadingEdge/Assets/Scripts/LoadableAudioClipReference.cs ScriptableObject referencing AudioClips via serialized Dictionary<string, Loadable<AudioClip>>.
UnityProjects/LeadingEdge/Assets/Scripts/DirectScriptableObjectReference.cs.meta Unity metadata for DirectScriptableObjectReference.
UnityProjects/LeadingEdge/Assets/Scripts/DirectScriptableObjectReference.cs ScriptableObject referencing other ScriptableObjects via a serialized dictionary (root aggregation).
UnityProjects/LeadingEdge/Assets/Scripts/DirectAudioClipReference.cs.meta Unity metadata for DirectAudioClipReference.
UnityProjects/LeadingEdge/Assets/Scripts/DirectAudioClipReference.cs ScriptableObject referencing AudioClips directly via serialized dictionary.
UnityProjects/LeadingEdge/Assets/Scripts.meta Unity folder metadata for Assets/Scripts.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SingleAudioClipLoadableReference.asset.meta Unity metadata for a single-clip loadable reference asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SingleAudioClipLoadableReference.asset Deterministic ScriptableObject asset referencing a.mp3 via Loadable.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SingleAudioClipDirectReference.asset.meta Unity metadata for a single-clip direct reference asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SingleAudioClipDirectReference.asset Deterministic ScriptableObject asset referencing a.mp3 directly.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SerializationDemo.asset.meta Unity metadata for SerializationDemo.asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/SerializationDemo.asset Deterministic serialization fixture asset for dump tests.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/LoadableAudioClipReference.asset.meta Unity metadata for LoadableAudioClipReference.asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/LoadableAudioClipReference.asset Deterministic multi-clip loadable reference asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/DirectAudioClipReference.asset.meta Unity metadata for DirectAudioClipReference.asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/DirectAudioClipReference.asset Deterministic multi-clip direct reference asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/ContentDirectoryRoot.asset.meta Unity metadata for the Content Directory build root asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/ContentDirectoryRoot.asset Root ScriptableObject asset for the Content Directory build scenario.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/AssetBundleRoot.asset.meta Unity metadata for the AssetBundle build root asset.
UnityProjects/LeadingEdge/Assets/ScriptableObjects/AssetBundleRoot.asset Root ScriptableObject asset for the AssetBundle build scenario.
UnityProjects/LeadingEdge/Assets/ScriptableObjects.meta Unity folder metadata for Assets/ScriptableObjects.
UnityProjects/LeadingEdge/Assets/Scenes/SampleScene.unity.meta Unity metadata for a sample scene.
UnityProjects/LeadingEdge/Assets/Scenes/SampleScene.unity Minimal scene content for the LeadingEdge project.
UnityProjects/LeadingEdge/Assets/Scenes.meta Unity folder metadata for Assets/Scenes.
UnityProjects/LeadingEdge/Assets/InputSystem_Actions.inputactions.meta Unity metadata for input actions asset.
UnityProjects/LeadingEdge/Assets/Editor/GenerateAssets.cs.meta Unity metadata for GenerateAssets editor script.
UnityProjects/LeadingEdge/Assets/Editor/GenerateAssets.cs Editor script to generate deterministic ScriptableObject assets for test builds.
UnityProjects/LeadingEdge/Assets/Editor/BuildContentDirectory.cs.meta Unity metadata for Content Directory build script.
UnityProjects/LeadingEdge/Assets/Editor/BuildContentDirectory.cs Editor script to build and copy Content Directory output into checked-in test data.
UnityProjects/LeadingEdge/Assets/Editor/BuildAssetBundles.cs.meta Unity metadata for AssetBundle build script.
UnityProjects/LeadingEdge/Assets/Editor/BuildAssetBundles.cs Editor script to build and copy AssetBundles output into checked-in test data.
UnityProjects/LeadingEdge/Assets/Editor.meta Unity folder metadata for Assets/Editor.
UnityProjects/LeadingEdge/Assets/Audio/a.mp3.meta Unity metadata for a.mp3 test audio.
UnityProjects/LeadingEdge/Assets/Audio/6.mp3.meta Unity metadata for 6.mp3 test audio.
UnityProjects/LeadingEdge/Assets/Audio.meta Unity folder metadata for Assets/Audio.
UnityProjects/LeadingEdge/AGENTS.md Documentation for updating LeadingEdge project and its generated outputs.
UnityProjects/Baseline/CLAUDE.md Points to the Baseline project’s agent guidance.
UnityProjects/Baseline/Assets/SerializeReferencePolymorphismExample.cs.meta Unity metadata for SerializeReference example component.
UnityProjects/Baseline/Assets/SerializeReferencePolymorphismExample.cs SerializeReference polymorphism fixture script.
UnityProjects/Baseline/Assets/Scenes/SampleSceneSettings.lighting.meta Unity metadata for Baseline lighting settings asset.
UnityProjects/Baseline/Assets/Scenes/SampleSceneSettings.lighting Baseline lighting settings fixture.
UnityProjects/Baseline/Assets/Scenes/SampleScene.unity.meta Unity metadata for Baseline sample scene.
UnityProjects/Baseline/Assets/Scenes/SampleScene.unity Baseline sample scene fixture.
UnityProjects/Baseline/Assets/Scenes/OtherScene.unity.meta Unity metadata for Baseline other scene.
UnityProjects/Baseline/Assets/Scenes/OtherScene.unity Baseline other scene fixture (player build source).
UnityProjects/Baseline/Assets/Scenes.meta Unity folder metadata for Baseline scenes.
UnityProjects/Baseline/Assets/Editor/TypeIdRegistryGenerator.cs.meta Unity metadata for TypeId registry generator script.
UnityProjects/Baseline/Assets/Editor/TypeIdRegistryGenerator.cs Editor script to regenerate UnityFileSystem/TypeIdRegistry.cs.
UnityProjects/Baseline/Assets/Editor/BuildAssetBundles.cs.meta Unity metadata for Baseline build script.
UnityProjects/Baseline/Assets/Editor/BuildAssetBundles.cs Baseline build scripts for AssetBundles and PlayerData generation.
UnityProjects/Baseline/Assets/Editor.meta Unity folder metadata for Baseline editor scripts.
UnityProjects/Baseline/Assets/AssetBundleData/wood.jpg.meta Unity metadata for texture fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Sting-Sword lowpoly.fbx.meta Unity metadata for FBX fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Square_Soft_A_Cookie.tif.meta Unity metadata for TIFF fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Robot_Basic.fbx.meta Unity metadata for FBX fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Prefab.prefab.meta Unity metadata for prefab fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Prefab.prefab Prefab fixture content.
UnityProjects/Baseline/Assets/AssetBundleData/Material.mat.meta Unity metadata for material fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Material.mat Material fixture content.
UnityProjects/Baseline/Assets/AssetBundleData/LegacyAnimation.anim.meta Unity metadata for legacy animation fixture.
UnityProjects/Baseline/Assets/AssetBundleData/LegacyAnimation.anim Legacy animation clip fixture.
UnityProjects/Baseline/Assets/AssetBundleData/blip.wav.meta Unity metadata for WAV fixture.
UnityProjects/Baseline/Assets/AssetBundleData/blip.wav WAV audio fixture.
UnityProjects/Baseline/Assets/AssetBundleData/AnimatorControlle.controller.meta Unity metadata for animator controller fixture.
UnityProjects/Baseline/Assets/AssetBundleData/AnimatorControlle.controller Animator controller fixture content.
UnityProjects/Baseline/Assets/AssetBundleData/Animation.anim.meta Unity metadata for animation fixture.
UnityProjects/Baseline/Assets/AssetBundleData/Animation.anim Animation clip fixture.
UnityProjects/Baseline/Assets/AssetBundleData.meta Unity folder metadata for Baseline AssetBundleData.
UnityProjects/Baseline/Assets/AssetBundle2Data/Shader.shader.meta Unity metadata for shader fixture.
UnityProjects/Baseline/Assets/AssetBundle2Data/Shader.shader Shader fixture content.
UnityProjects/Baseline/Assets/AssetBundle2Data.meta Unity folder metadata for Baseline AssetBundle2Data.
UnityProjects/Baseline/AGENTS.md Documentation for Baseline project purpose and generation scripts.
UnityFileSystem/TypeIdRegistry.cs Update generator path reference to new Baseline location.
UnityDataTool/Program.cs Add --stdout for find-refs + mutual-exclusion validation; plumb flag into handler.
UnityDataTool.Tests/FindRefsTests.cs New NUnit coverage for find-refs behavior and regressions (issue #72 + ScriptableObject NULL handling).
UnityDataTool.Tests/ExpectedDataGenerator.cs Use shared DB open helper instead of invalid connection string keyword.
UnityDataTool.Tests/DumpTests.cs Add test that dumps SerializationDemo from LeadingEdge AssetBundle output.
TestCommon/Data/PlayerData/CLAUDE.md Points to agent guidance for PlayerData test data.
TestCommon/Data/PlayerData/AGENTS.md Documentation for PlayerData test fixture generation.
TestCommon/Data/LeadingEdgeBuilds/ContentDirectory/BuildManifestHash.txt Checked-in LeadingEdge Content Directory manifest hash.
TestCommon/Data/LeadingEdgeBuilds/ContentDirectory/15d5df98d98434e67e06716cfabfad1b.json Checked-in LeadingEdge Content Directory build manifest JSON.
TestCommon/Data/LeadingEdgeBuilds/CLAUDE.md Points to agent guidance for LeadingEdge builds.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/ScriptsOnlyCache.yaml Checked-in Content Directory build report artifact.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/ContentSizeSummary.txt Checked-in Content Directory build report summary.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/ContentLayout.json Checked-in Content Directory content layout for analysis/testing.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/BuildReportSummary.json Checked-in Content Directory build report summary JSON.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/BuildLog.jsonl Checked-in Content Directory build log.
TestCommon/Data/LeadingEdgeBuilds/BuildReport-ContentDirectory/BuildContentTEP.json Checked-in tracing artifact for Content Directory build.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/singleaudioclipdirectreference.manifest Checked-in AssetBundle manifest for deterministic test inputs.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/serializationdemo.manifest Checked-in AssetBundle manifest for serialization fixture.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/directaudioclipreference.manifest Checked-in AssetBundle manifest for AudioClip reference fixture.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/AssetBundles.manifest Checked-in overall AssetBundles manifest.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/assetbundleroot.manifest Checked-in AssetBundle manifest for root aggregation fixture.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/a.manifest Checked-in AssetBundle manifest for a.mp3.
TestCommon/Data/LeadingEdgeBuilds/AssetBundles/6.manifest Checked-in AssetBundle manifest for 6.mp3.
TestCommon/Data/LeadingEdgeBuilds/AGENTS.md Documentation for the LeadingEdge checked-in build outputs and layout.
TestCommon/Data/AssetBundles/CLAUDE.md Points to agent guidance for AssetBundle test data.
TestCommon/Data/AssetBundles/AGENTS.md Documentation for AssetBundle test fixture generation.
ReferenceFinder/ReferenceFinderTool.cs Fix connection string construction; add --stdout support; null-check correlated-subquery reads.
README.md Update repository overview to reflect new UnityProjects folder.
Documentation/command-find-refs.md Document traversal behavior and new --stdout option.
CLAUDE.md Point to root AGENTS.md.
AGENTS.md Update repo-wide agent guidance to document Baseline/LeadingEdge Unity projects.
.gitignore Update ignores to cover new UnityProjects layout and generated folders.

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

Comment thread ReferenceFinder/ReferenceFinderTool.cs
Comment thread ReferenceFinder/ReferenceFinderTool.cs
Comment thread ReferenceFinder/ReferenceFinderTool.cs
Comment thread UnityDataTool.Tests/FindRefsTests.cs
Comment on lines +52 to +59
try
{
Directory.Delete(m_WorkFolder, true);
}
catch (IOException)
{
// Best effort cleanup; leftover files in the test output folder are harmless.
}
@SkowronskiAndrew
[#72] Fix find-refs database open and null-ref crashes, add test cove…
e3046f7 
…rage

find-refs had no automated tests and two bugs that broke it against any
current analyze database:

- Issue #72: the database was opened with a hand-written connection string
  using the legacy System.Data.SQLite "Version=3" keyword, which
  Microsoft.Data.Sqlite rejects. Build the connection string with
  SqliteConnectionStringBuilder instead (matching SQLiteWriter). Fixed the
  same broken string in ExpectedDataGenerator.

- A ScriptableObject is a MonoBehaviour whose m_GameObject PPtr is 0, so its
  game_object column is a non-null id matching no row; the game_object/script
  subqueries then return NULL and GetString threw. Null-check those reads.

Also add a --stdout option to find-refs (mutually exclusive with -o), mirroring
dump, and update command-find-refs.md.

Add FindRefsTests covering both bugs, name/type lookup and disambiguation,
object-id lookup, --find-all, missing objects, empty refs table, the
--stdout/-o validator, and direct refs-table queries. Tests run against the
LeadingEdge AssetBundle reference build.
@SkowronskiAndrew SkowronskiAndrew merged commit 88984ab into main Jul 2, 2026
5 checks passed
@SkowronskiAndrew SkowronskiAndrew deleted the fix-find-ref branch July 2, 2026 13:46
@SkowronskiAndrew SkowronskiAndrew mentioned this pull request Jul 2, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@SkowronskiAndrew