t1k:unity:architecture:dep-reconciler
| Field | Value |
|---|---|
| Module | architecture |
| Version | 3.37.4 |
| Effort | medium |
| Tools | — |
Keywords: asmdef dependencies, assembly references audit, dangling reference, dependency reconciler, missing reference, prune references, scoped, sweep one package, unused asmdef, unused reference
How to invoke
Section titled “How to invoke”/t1k:unity:architecture:dep-reconcilerunity-dep-reconciler
Section titled “unity-dep-reconciler”Type-level reconciliation of a Unity project’s dependency declarations. It answers three questions per assembly, then optionally writes the fix:
| Finding | Meaning | Detected by |
|---|---|---|
| MISSING | The code uses a type from assembly X, but X is not declared | Roslyn symbol resolution |
| UNUSED | X is declared in references, but no type from X is used | Roslyn symbol resolution |
| DANGLING | X is declared but resolves to no assembly on disk | name + GUID index |
Only a type-level analysis can detect UNUSED. A structural asmdef→asmdef walk cannot: nothing in the reference graph records whether code touches the assembly. That is the capability this skill exists for.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “What’s wrong with this project’s references?” | Dry-run → Usage. Writes nothing. |
| “Fix the missing references” | Review the dry-run, then --apply → Usage |
| “I only care about one package or assembly” | --target → Usage · Scoped sweeps |
| “Why is this reference dangling?” | references/findings-taxonomy.md |
| “It refuses to run / exits 1” | Prerequisites — Unity’s reference assemblies are missing |
| “Does the GameFoundation tool already do this?” | In-editor counterpart |
# Dry-run: report only, nothing written. This is the DEFAULT.bun scripts/reconcile.cjs --project-root /path/to/UnityProject
# Write the fix. Requires an explicit flag.# `--apply` ALSO normalizes every writable .asmdef and UPM package.json in the swept set.bun scripts/reconcile.cjs --project-root /path/to/UnityProject --apply
# Point at Unity's managed assemblies explicitly when the editor is not at the# path the generated .csproj files expect.bun scripts/reconcile.cjs --project-root <proj> --unity-managed-path <dir>
# Sweep ONE target — a folder, an asmdef name, or a package name — instead of the# whole project. Repeatable; the occurrences union into one swept set.bun scripts/reconcile.cjs --project-root <proj> --target VoxelColor.Gameplaybun scripts/reconcile.cjs --project-root <proj> --target com.gdk.corebun scripts/reconcile.cjs --project-root <proj> --target Assets/_Game/VoxelColorbun scripts/reconcile.cjs --project-root <proj> --target A --target B
# Is this a Unity project at all? exit 0 = yes, 1 = nobun scripts/detect.cjs --project-root /path/to/UnityProjectOptions: --apply · --unity-managed-path <dir> · --target <name|path> (repeatable) ·
--target-kind <auto|folder|asmdef|package> · --json · --include-package-cache · --help
Normalization rides --apply
Section titled “Normalization rides --apply”--apply also normalizes every writable .asmdef and UPM package.json in the swept set: canonical property order, rootNamespace removed, overrideReferences: true, 2-space indent. The dry run prints the full before/after per file, so review it before applying. Never chain prettier, csharpier, dprint or biome after it: the normalizer is the formatter. Per-file rules, the normalizeEdits[] contract and the non-UPM manifest exclusion: references/normalization.md.
Scoped sweeps
Section titled “Scoped sweeps”--target narrows the run to one target plus its folder-nested children plus the
transitive closure of the references that set declares. The result is reported under a
top-level scope block:
"scope": { "target": ["VoxelColor.Gameplay"], "matched": 1, "swept": 59, "ofProject": 977 }Read scope.swept against scope.ofProject before drawing any conclusion from a scoped run: 0 findings is not “clean”, and scoping leaves coverageStatus unchanged. The misreadings, containment rule, package-dependency walk and not-found exit (1) are in references/scoped-sweeps.md.
Prerequisites
Section titled “Prerequisites”Unity’s reference assemblies must be resolvable, or the analysis refuses to run. Roslyn
cannot resolve UnityEngine.CoreModule and friends without them, and without that every Unity
type reads as unknown — producing a flood of false MISSING findings.
The tool resolves them from the <HintPath> entries Unity writes into the generated
*.csproj files. If the editor install has moved or been removed, those paths are dead and
the run stops rather than guessing:
coverageStatus: NOT_CHECKEDreason: missing-unity-reference-assembliesExit code 1 — not 2, and never a clean pass. Do not substitute reference assemblies from
another Unity version: a different patch release has a different API surface, so the analysis
would resolve against the wrong contract and report confidently wrong results. Install the
editor version the project pins (ProjectSettings/ProjectVersion.txt), or pass
--unity-managed-path (its dir must hold UnityEngine.CoreModule.dll; dead HintPaths are then resolved against it).
Exit Codes
Section titled “Exit Codes”| Code | Meaning |
|---|---|
0 | Analysis ran. Findings may or may not exist — read the JSON, not the exit code |
1 | Could not run (NOT_CHECKED), or an apply failed |
2 | Usage / bad argument only |
0 does not mean “clean”. A run that found three MISSING references exits 0. Always
check coverageStatus first: ANALYZED means the findings are real, NOT_CHECKED means
nothing was examined.
In-editor counterpart — read before building anything here
Section titled “In-editor counterpart — read before building anything here”A substantial overlapping tool already exists, and this skill must not be extended into its territory:
GameFoundation.Editor.PackageRegistry.DependencyGraph — ships in the com.gdk.core
package (submodule The1Studio/GameFoundation.git, ~4,000 lines). It propagates
package.json dependencies from asmdef references, with its own dry-run, confirmation flow,
and ignored-packages config.
Boundary:
| Concern | Owner |
|---|---|
| Type-level missing / unused detection | this skill |
Rewriting the asmdef references array | this skill |
| Headless / CI runs with no Editor | this skill |
Propagating package.json deps from asmdef refs, in-Editor | GameFoundation |
| Registry publishing, version sync, commit tracking | GameFoundation |
Running both over package.json will contend — they can each write the same file. Pick
one. See references/in-editor-counterpart.md.
Correctness rules
Section titled “Correctness rules”Each of these is a measured false-positive class, not a style preference. Full detail with the measured numbers: references/findings-taxonomy.md.
-
Index four scan roots, not two.
Assets/,Packages/,Library/PackageCache/, and the editor’sBuiltInPackages/. ~250 asmdefs ship inside the editor install. Omitting that root alone was measured at 208 reported dangling → 45 real. -
Index
*.dllbasenames alongside asmdef names. A precompiled DLL never appears in an asmdef-name index, so it reads as dangling unless DLL names are indexed too. -
overrideReferences: falsebypassesprecompiledReferences. Unity then auto-references every project precompiled assembly, so a missing-precompiled finding there is wrong. Only enforced when the flag istrue— which normalization now FORCES, so in practice the list is always live after an--apply. -
Removals of convention-reached or platform-conditional references are reported, never auto-applied. This covers the TestRunner references (all 20 TestRunner asmdefs keep both), the explicit
CONVENTION_REACHEDallowlist indiff.cjs(never aUnitynamespace pattern) andprecompiledReferencesremovals (an#if UNITY_ANDROIDDLL looks unused on desktop). Additions still auto-apply. Detail:references/apply-holds.md. -
A
.dllentry is matched to an assembly name by its STEM.precompiledReferencesholds filenames (CsvHelper.dll);usedandresolvablehold assembly names (CsvHelper). Both sides are stem-normalized, which is what fixes the false-danglingnunit.framework.dll. -
Dangling references are not build blockers. Unity 6 drops an unresolvable
referencesentry with a warning and compiles anyway — verified against a project that built 974 assemblies while carrying 74 dangling refs. Triage the list; do not treat it as a build failure. -
Dangling refs originating inside
Library/PackageCache/are suppressed. They are upstream packages’ problems and drown out the ones you can act on.
Hard rules
Section titled “Hard rules”-
--applyis not a mode toggle you can forget you passed. Dry-run is the default for a reason: these files have no compile-time guard, so a bad edit surfaces only at the next Unity compile. -
⚠ A NON-EMPTY
includePlatformsis NEVER stripped — and that is the single most dangerous thing normalization could get wrong.includePlatforms: ["Editor"]is load-bearing: it keeps an editor-only assembly out of every runtime build. Stripping it merges editor code into the player build, where it surfaces as a compile error in the player (not the editor) or, worse, ships editor-only code. Measured on the target project: 318 of 977 asmdefs carry a non-emptyincludePlatforms. Only the EMPTY[]form falls under strip-if-default. If a future change to the strip predicate ever widens this, the regression test that pins it is intests/normalize.test.cjs. -
--applyalso normalizes. ReadnormalizeEdits[](or thewould rewritediff) before approving: the before/after is what you approve, not the reference counts. Seereferences/normalization.md. -
A low-confidence finding is reported, never applied. Ambiguous or partially-resolved symbols are left for a human deliberately — do not “fix” them by hand-editing the suggestion into the file.
-
0is not “clean”. CheckcoverageStatus. On a scoped run it is doubly true:0findings means nothing in the swept set had a finding, and the swept set may be a fraction of the project. Readscopebefore concluding anything — that is what it is for. -
coverageStatusis not changed by scoping. A scoped run that reached the analysis still reportsANALYZED, so acoverageStatus === 'ANALYZED'check is not evidence that the whole project was examined. It never was: scope is reported separately inscope. -
A package target matches the folder key. For an embedded package under
Packages/that key can differ from thenamein itspackage.json(measured:Packages/com.gdk.coredeclaresname: com.theone.gdk.core). Both are accepted — the declared name is read as an alias — but the folder key is what the tree actually provides. -
Containment applies once, at the target, and scope counts asmdef nodes. A same-directory sibling is not a child, and a dependency’s own children do not come along. A
~977denominator and a package run reading13 of 977are honest. Seereferences/scoped-sweeps.md. -
The generated
*.csprojfiles are the manifest source, not the asmdefs. Unity already resolved every reference there, including transitive ones. Reading asmdefs to re-derive resolution duplicates work Unity did and gets it wrong. -
A project-owned dependency is a
ProjectReference, and its metadata comes fromLibrary/ScriptAssemblies/. That is Unity’s last compiled output, so a run immediately after editing sources — before Unity recompiles — can under-reportused. See references/roslyn-analysis.md § “Project-owned dependencies”. -
Assets/PlayFabEditorExtensions/Editor/PlayFabEditorExtensions.asmdefcarries a UTF-8 BOM. Any reader must strip a leadingbeforeJSON.parseor it fails on a file that looks entirely valid in an editor. -
Assembly names with spaces are real (e.g.
Sirenix.OdinInspector.Modules.UnityMathematicsunder a path with spaces). Do not assume paths have no spaces.
Executed by
Section titled “Executed by”The collection and reconciliation steps are enumerated and mechanical; only the decision to
write stays on a reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type →
Agent Routing”):
| Step | Agent |
|---|---|
| Run the reconciler and read the per-assembly findings off the JSON | t1k-fact-fetcher |
| Aggregate the findings into a counts-by-kind summary | t1k-metrics-reporter |
| Label each finding MISSING / UNUSED / DANGLING against the taxonomy | t1k-list-classifier |
| Decide which high-confidence findings to apply | reasoning tier — a write to a user’s build files, not a label |
| Diagnose why a specific reference is dangling | reasoning tier — t1k-debugger; a cause is not a verdict |
The first three rows are fully specified by the report contract and the taxonomy, which is what makes them cheap-tier work. The moment the question turns from what did it find? to should this reference exist at all, it has changed tier.
References
Section titled “References”| File | Content |
|---|---|
| references/findings-taxonomy.md | The three finding kinds, confidence levels, false-positive classes with measured numbers |
| references/roslyn-analysis.md | Compilation model, reference-set resolution, define constraints, the NOT_CHECKED guard |
| references/apply-safety.md | Atomic-write contract, round-trip check, what is never applied |
| references/in-editor-counterpart.md | The GameFoundation boundary in full |
Related
Section titled “Related”t1k-unity-architecture-assembly-graph— the read-only diagram adapter this skill borrows its asmdef parser from, and which documents the four-scan-root rulet1k-unity-base-lib-packaging— contributes code into a package; this skill audits the dependencies of one that already existst1k-unity-base-upm-auth— registry credential failures, which produce a similar-looking massCS0246cascade that is an auth problem, not a dependency problem