Skip to content

t1k:unity:architecture:dep-reconciler

FieldValue
Modulearchitecture
Version3.37.4
Effortmedium
Tools—

Keywords: asmdef dependencies, assembly references audit, dangling reference, dependency reconciler, missing reference, prune references, scoped, sweep one package, unused asmdef, unused reference

/t1k:unity:architecture:dep-reconciler

Type-level reconciliation of a Unity project’s dependency declarations. It answers three questions per assembly, then optionally writes the fix:

FindingMeaningDetected by
MISSINGThe code uses a type from assembly X, but X is not declaredRoslyn symbol resolution
UNUSEDX is declared in references, but no type from X is usedRoslyn symbol resolution
DANGLINGX is declared but resolves to no assembly on diskname + 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.

IntentPath
“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
Terminal window
# 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.Gameplay
bun scripts/reconcile.cjs --project-root <proj> --target com.gdk.core
bun scripts/reconcile.cjs --project-root <proj> --target Assets/_Game/VoxelColor
bun scripts/reconcile.cjs --project-root <proj> --target A --target B
# Is this a Unity project at all? exit 0 = yes, 1 = no
bun scripts/detect.cjs --project-root /path/to/UnityProject

Options: --apply · --unity-managed-path <dir> · --target <name|path> (repeatable) · --target-kind <auto|folder|asmdef|package> · --json · --include-package-cache · --help

--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.

--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.

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_CHECKED
reason: missing-unity-reference-assemblies

Exit 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).

CodeMeaning
0Analysis ran. Findings may or may not exist — read the JSON, not the exit code
1Could not run (NOT_CHECKED), or an apply failed
2Usage / 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:

ConcernOwner
Type-level missing / unused detectionthis skill
Rewriting the asmdef references arraythis skill
Headless / CI runs with no Editorthis skill
Propagating package.json deps from asmdef refs, in-EditorGameFoundation
Registry publishing, version sync, commit trackingGameFoundation

Running both over package.json will contend — they can each write the same file. Pick one. See references/in-editor-counterpart.md.

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’s BuiltInPackages/. ~250 asmdefs ship inside the editor install. Omitting that root alone was measured at 208 reported dangling → 45 real.

  • Index *.dll basenames 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: false bypasses precompiledReferences. Unity then auto-references every project precompiled assembly, so a missing-precompiled finding there is wrong. Only enforced when the flag is true — 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_REACHED allowlist in diff.cjs (never a Unity namespace pattern) and precompiledReferences removals (an #if UNITY_ANDROID DLL looks unused on desktop). Additions still auto-apply. Detail: references/apply-holds.md.

  • A .dll entry is matched to an assembly name by its STEM. precompiledReferences holds filenames (CsvHelper.dll); used and resolvable hold assembly names (CsvHelper). Both sides are stem-normalized, which is what fixes the false-dangling nunit.framework.dll.

  • Dangling references are not build blockers. Unity 6 drops an unresolvable references entry 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.

  • --apply is 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 includePlatforms is 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-empty includePlatforms. 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 in tests/normalize.test.cjs.

  • --apply also normalizes. Read normalizeEdits[] (or the would rewrite diff) before approving: the before/after is what you approve, not the reference counts. See references/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.

  • 0 is not “clean”. Check coverageStatus. On a scoped run it is doubly true: 0 findings means nothing in the swept set had a finding, and the swept set may be a fraction of the project. Read scope before concluding anything — that is what it is for.

  • coverageStatus is not changed by scoping. A scoped run that reached the analysis still reports ANALYZED, so a coverageStatus === 'ANALYZED' check is not evidence that the whole project was examined. It never was: scope is reported separately in scope.

  • A package target matches the folder key. For an embedded package under Packages/ that key can differ from the name in its package.json (measured: Packages/com.gdk.core declares name: 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 ~977 denominator and a package run reading 13 of 977 are honest. See references/scoped-sweeps.md.

  • The generated *.csproj files 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 from Library/ScriptAssemblies/. That is Unity’s last compiled output, so a run immediately after editing sources — before Unity recompiles — can under-report used. See references/roslyn-analysis.md § “Project-owned dependencies”.

  • Assets/PlayFabEditorExtensions/Editor/PlayFabEditorExtensions.asmdef carries a UTF-8 BOM. Any reader must strip a leading  before JSON.parse or it fails on a file that looks entirely valid in an editor.

  • Assembly names with spaces are real (e.g. Sirenix.OdinInspector.Modules.UnityMathematics under a path with spaces). Do not assume paths have no spaces.

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”):

StepAgent
Run the reconciler and read the per-assembly findings off the JSONt1k-fact-fetcher
Aggregate the findings into a counts-by-kind summaryt1k-metrics-reporter
Label each finding MISSING / UNUSED / DANGLING against the taxonomyt1k-list-classifier
Decide which high-confidence findings to applyreasoning tier — a write to a user’s build files, not a label
Diagnose why a specific reference is danglingreasoning 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.

FileContent
references/findings-taxonomy.mdThe three finding kinds, confidence levels, false-positive classes with measured numbers
references/roslyn-analysis.mdCompilation model, reference-set resolution, define constraints, the NOT_CHECKED guard
references/apply-safety.mdAtomic-write contract, round-trip check, what is never applied
references/in-editor-counterpart.mdThe GameFoundation boundary in full
  • t1k-unity-architecture-assembly-graph — the read-only diagram adapter this skill borrows its asmdef parser from, and which documents the four-scan-root rule
  • t1k-unity-base-lib-packaging — contributes code into a package; this skill audits the dependencies of one that already exists
  • t1k-unity-base-upm-auth — registry credential failures, which produce a similar-looking mass CS0246 cascade that is an auth problem, not a dependency problem