com.elestrago.unity.generated-code-dump 1.0.0

package/Documentation~/manual.md

@@ -0,0 +1,618 @@
+# Generated Code Dump — Manual
+
+This is the full guide to the package. The [README](../README.md) is the quick start, and the [examples](examples.md) walk through single tasks. The last section, [Internals](#internals), is for contributors.
+
+## What it does
+
+After Unity compiles `Assembly-CSharp` in this package's example project, this file appears on disk:
+
+```text
+Library/GeneratedCodeDump/Assembly-CSharp/GeneratedCodeDump.TestGenerators.Incremental/Example.ExampleBehaviour.Dumpable.g.cs
+```
+
+It is the code a source generator added to that compile. A *source generator* is a plug-in for the C# compiler that writes extra source code while an assembly compiles. Unity runs source generators during its compile, but it never saves what they write.
+
+Without the files on disk, a tool or an AI agent reading the project sees only the attributes and `partial` declarations. It does not see the members the generators add, so it has to guess them. This package writes the output of every Roslyn source generator in the project to `Library/GeneratedCodeDump/` after each compile, so tools and agents can read the real generated code.
+
+To get the files, the package *replays* each assembly's compile. A *replay* runs Unity's own compiler again for one assembly, with the same inputs Unity used, but sends its outputs to the dump's own folders instead of Unity's. The package keeps the generated files and adds header lines that name the dump time, the assembly, the generator and the file's name.
+
+- The package is Editor-only. Nothing from it ships in a player build.
+- The dump goes under `Library/` and the switch under `UserSettings/`. Nothing is added to `Assets/` or to the compile.
+- The package only reads Unity's build files. Unity's own compile outputs under `Library/Bee/` are never touched.
+- You control it with a per-user settings file, the `Tools/Generated Code Dump/` menu and the `Preferences/Generated Code Dump` page. There is no C# API to call.
+
+## Turning it on and off
+
+From the Unity project root, these two lines turn the dump on:
+
+```bash
+mkdir -p UserSettings
+printf '{"enabled": true}\n' > UserSettings/GeneratedCodeDumpSettings.json
+```
+
+The dump is off by default. The switch belongs to one user in one project. There are three ways to flip it, and all three write the same file:
+
+- **Preferences:** the `Preferences/Generated Code Dump` page, toggle `Dump generated code`.
+- **Menu:** `Tools/Generated Code Dump/Enabled`, which shows a checkmark while the dump is on.
+- **File:** write `UserSettings/GeneratedCodeDumpSettings.json` yourself, as above.
+
+A step-by-step version is in [Turn on the dump](examples/turn-on-the-dump.md).
+
+### The settings file
+
+The file holds one flat JSON object. `enabled` must be exactly `true` or `false`, and a missing `enabled` means off. Other keys may sit next to it if their values are plain: a string, a number, `true`, `false` or `null`.
+
+A missing file, or one that is not valid, means off. An invalid file also logs a warning:
+
+```text
+[Generated Code Dump] <full path of the file> is not valid: expected {"enabled": true} or false. The dump is off.
+```
+
+The warning is not repeated while the file stays the same. If you edit the file and it is still invalid, it warns again.
+
+### When a change applies
+
+- **Open Editor:** it watches the file, even while it is in the background, and applies an edit within about a second. A change from the menu or the Preferences page applies at once.
+- **No `UserSettings/` folder yet:** the Editor watches the project root for that folder to appear. Watching creates nothing.
+- **Closed Editor:** it reads the file at its next start.
+- **Batch mode:** an Editor started with `-batchmode` on the same checkout reads the file when it starts.
+
+### One switch per developer
+
+`UserSettings/` is Unity's per-user folder. The switch survives deleting `Library/`, and each developer turns the dump on for themselves.
+
+Unity's standard `.gitignore` ignores `/[Uu]ser[Ss]ettings/`. If yours does not, add that line, or the switch gets committed for everyone.
+
+### Turning it off
+
+Untick the toggle or the menu item, write `{"enabled": false}` to the file, or delete the file. Turning the dump off drops the replays that have not started yet. A compiler that is already running still finishes, and its files still land.
+
+The existing `Library/GeneratedCodeDump/` folder is kept, but later compiles no longer refresh it. After that, nothing under `Library/GeneratedCodeDump/` is created while the dump is off, except by Dump Now or Open Folder (see [The other menu items](#the-other-menu-items)).
+
+One more file can be written while the dump is off without you asking: the new settings file, when an upgrade from 1.0.0 moves a setting that was off. See [Upgrading from 1.0.0](#upgrading-from-100).
+
+### The other menu items
+
+| Menu item | What it does |
+| --- | --- |
+| `Tools/Generated Code Dump/Dump Now` | Starts a full dump, which refreshes the whole dump (see [When a dump runs](#when-a-dump-runs)), whatever the setting. It also works while the dump is off, as a one-off refresh. |
+| `Tools/Generated Code Dump/Open Folder` | Creates `Library/GeneratedCodeDump/` if needed and opens it in the system's file browser. |
+| `Tools/Generated Code Dump/Preferences…` | Opens the `Preferences/Generated Code Dump` page. |
+
+Dump Now and Open Folder are also buttons on the Preferences page. Neither of them turns the dump on. The settings file is the only switch; there is no command-line flag. See also [Dump Now and Open Folder](examples/dump-now.md).
+
+## When a dump runs
+
+When you turn the dump on, the Console shows a line like this:
+
+```text
+[Generated Code Dump] queued 11 assemblies, at most 6 compiling at once; output in Library/GeneratedCodeDump/
+```
+
+That line starts a *full dump*: a replay of every assembly from Unity's latest compile that loads an analyzer. An *analyzer* is a plug-in DLL the compiler is told to load for an assembly. Source generators ship as analyzers, so an assembly that loads none has no generated files and is never replayed.
+
+### What starts a full dump
+
+- You turn the dump on, in any of the three ways.
+- An Editor starts with the dump on, batch mode included.
+- A domain reload or a change of the setting finds `Library/GeneratedCodeDump/` missing while the dump is on. A *domain reload* is Unity reloading its scripts, which it does after every compile. So deleting that folder while the dump is on forces a full dump at the next reload.
+- You choose Dump Now, even while the dump is off.
+
+A full dump always starts with the `queued` line above. The number after `queued` counts the assemblies that load an analyzer. The "at most" number is explained in [Performance](#performance).
+
+### Editor start or domain reload?
+
+When an Editor first finds the dump on, it writes a small marker file, `Library/GeneratedCodeDump/.work/enabled-session`, that names that Editor process. A domain reload in the same Editor finds its own marker and skips the full dump. A new Editor finds another process's marker, so it runs one.
+
+### After each compile
+
+Once the full dump is done, every compile runs a *per-compile dump*. It replays only the assemblies rebuilt by that compile without errors, and of those only the ones that load an analyzer.
+
+An assembly that failed to compile is skipped by the per-compile dump until it compiles again. A full dump does not check this: it replays every assembly of the newest build graph that loads an analyzer.
+
+### Jobs
+
+Each requested replay is a *job*: one replay of one assembly. The dump writes its jobs to `Library/GeneratedCodeDump/.work/jobs.txt`, marked queued or running, until the output is in place. A dump cut short by a domain reload or an Editor restart therefore picks up where it stopped.
+
+Each assembly has at most one job waiting. When a dump is requested for an assembly whose job is still queued, that job covers it, since a job reads Unity's compiler arguments only when it starts. When one is requested while the assembly's compiler is running, the assembly is replayed once more afterwards.
+
+## Reading the output
+
+A real dump of this package's own example project looks like this. Its test generators live in the repository's `External/` folder and are not shipped:
+
+```text
+Library/GeneratedCodeDump/
+  .work/
+  Assembly-CSharp/
+    GeneratedCodeDump.TestGenerators.Classic/
+      Aux_.g.cs
+      ExampleBehaviour.generated.cs
+      ExampleBehaviour~31a944ea.generated.cs
+    GeneratedCodeDump.TestGenerators.Incremental/
+      Example.ExampleBehaviour.Dumpable.g.cs
+      Summary.Info.g.cs
+    Unity.SourceGenerators/
+      AssemblyMonoScriptTypes.generated.cs
+  GeneratedCodeDump.Example.Module/
+    GeneratedCodeDump.TestGenerators.Classic/
+      Aux_.g.cs
+      DeepRecord.generated.cs
+      DeepRecord~5fee0560.generated.cs
+      ModuleService.generated.cs
+    GeneratedCodeDump.TestGenerators.Incremental/
+      GeneratedCodeDump.Example.Module.Deep.DeepRecord.Dumpable.g.cs
+      GeneratedCodeDump.Example.Module.ModuleService.Dumpable.g.cs
+      Summary.Info.g.cs
+    Unity.SourceGenerators/
+      AssemblyMonoScriptTypes.generated.cs
+  ...
+```
+
+The `...` stands for the project's other assemblies, such as the test runner's. Each of them holds only `Unity.SourceGenerators/AssemblyMonoScriptTypes.generated.cs`.
+
+### Folder and file names
+
+Every file sits at `Library/GeneratedCodeDump/<Assembly>/<GeneratorAssembly>/<hint name>`:
+
+- `<Assembly>` is the compiled assembly: `Assembly-CSharp`, or an asmdef name such as `GeneratedCodeDump.Example.Module`.
+- `<GeneratorAssembly>` is the *generator assembly*: the DLL the source generator ships in, named by its assembly name. Unity's own generator ships in `Unity.SourceGenerators`.
+- `<hint name>` is the *hint name*: the file name the source generator gave the file, such as `Example.ExampleBehaviour.Dumpable.g.cs`. It is kept exactly as the generator gave it, as one flat file name, with no namespace folders.
+
+Unity's `Unity.SourceGenerators` runs on most assemblies, so most assembly folders hold `AssemblyMonoScriptTypes.generated.cs`. In this package's example project it ran on every assembly.
+
+### Two generators, one hint name
+
+`ExampleBehaviour.generated.cs` and `ExampleBehaviour~31a944ea.generated.cs` in the tree above come from two generators in `GeneratedCodeDump.TestGenerators.Classic`. Both gave the hint name `ExampleBehaviour.generated.cs`, and one folder cannot hold two files with the same name.
+
+The generator whose full type name sorts first, in plain character order, keeps the name. Here that is `GeneratedCodeDump.TestGenerators.Classic.CollidingGenerator`. Two hint names that differ only in letter case also count as a shared hint name.
+
+The other one, `GeneratedCodeDump.TestGenerators.Classic.LegacyGenerator`, gets a *short hash* between the name and its ending. A short hash is a `~` and 8 lowercase hex digits, such as `~31a944ea`, computed with the FNV-1a 32-bit hash over the UTF-8 bytes of a name. The same name always gives the same short hash, on every machine, so the renamed file cannot clash with its twin and keeps its name from one dump to the next.
+
+For a shared hint name, the hashed name is `<generator full type name>/<hint name>`: here `GeneratedCodeDump.TestGenerators.Classic.LegacyGenerator/ExampleBehaviour.generated.cs`. The ending that stays after the short hash is `.generated.cs` or `.g.cs`, or else the file's extension.
+
+### Windows reserved names
+
+`Aux.g.cs` becomes `Aux_.g.cs`. Windows refuses a file or folder whose name part is `CON`, `PRN`, `AUX`, `NUL`, `COM0` to `COM9` or `LPT0` to `LPT9`, in any letter case and whatever follows the first dot. The dump adds `_` after that name part, for folders and files, on every OS.
+
+### Empty and removed files
+
+- An assembly whose generators produce nothing has no folder.
+- Each replay syncs its whole assembly folder. A file its generators no longer produce is deleted.
+
+### The `.work/` folder
+
+`.work/` sits next to the assembly folders. It is the dump's own bookkeeping: the job list, the session marker, and each assembly's last replay arguments and error log. It holds no generated code, so skip it when you search, with `grep --exclude-dir=.work`.
+
+On Windows `.work/` is Hidden, so Open Folder shows only the assembly folders. Its leading dot keeps it apart from every assembly name. Its contents are described in [Internals](#file-formats).
+
+### Header lines
+
+The top of `Assembly-CSharp/GeneratedCodeDump.TestGenerators.Incremental/Example.ExampleBehaviour.Dumpable.g.cs`:
+
+```csharp
+// <auto-generated/>
+// Dumped: 2026-09-12 10:15:03 UTC
+// Assembly: Assembly-CSharp
+// Generator: GeneratedCodeDump.TestGenerators.Incremental / GeneratedCodeDump.TestGenerators.Incremental.DumpableGenerator
+// Hint: Example.ExampleBehaviour.Dumpable.g.cs
+namespace Example
+{
+	partial class ExampleBehaviour
+```
+
+Every dumped file gets these four header lines. They always hold full names, even when the file or its folders got a shorter name (see [Long paths](#long-paths)):
+
+- `Dumped: yyyy-MM-dd HH:mm:ss UTC`: when the replay's compiler started, in UTC.
+- `Assembly: <Assembly>`: the compiled assembly.
+- `Generator: <GeneratorAssembly> / <generator full type name>`.
+- `Hint: <hint name>`: the hint name exactly as the generator gave it.
+
+Where the lines go depends on how the generator starts its file:
+
+- After a `// <auto-generated/>` line, as above.
+- At the end of a `// <auto-generated>` … `// </auto-generated>` block, indented as `//     Dumped: …`.
+- Otherwise, as the file's first lines.
+
+The dump looks for those markers in the first 12 lines. It keeps the file's byte order mark (BOM) and its line endings.
+
+### Line numbers are off by 4
+
+The header adds 4 lines above the generator's code. So when a compiler message points at line 10 of a generated file, look at line 14 of the dumped file. Lines above the header, such as a `// <auto-generated>` block, keep their numbers.
+
+### Stale files and files held open
+
+A file dumped before your last source edit is stale. Compare its `Dumped:` line with the time of your edit; the next compile of that assembly refreshes it while the dump is on.
+
+A file held open by another program cannot be replaced. It keeps its older content and its older `Dumped:` line, a warning names it (see [Warnings and failures](#warnings-and-failures)), and the next dump tries again. [Read the dump](examples/read-the-dump.md) shows these files being searched.
+
+## Long paths
+
+Take a Windows project with HDRP and UI Toolkit, whose root folder path is 103 characters long. One generated file of its HDRP editor assembly would get this path inside the project:
+
+```text
+Library/GeneratedCodeDump/Unity.RenderPipelines.HighDefinition.Editor/Unity.UIToolkit.SourceGenerator/UnityEditor.Rendering.HighDefinition.Compositor.CompositionLayerUIElement.UxmlSerializedData.g.cs
+```
+
+With the project path and a separator in front, that is 303 characters. Windows allows 259, so the dump shortens names, one step at a time, until the path fits:
+
+1. The assembly folder `Unity.RenderPipelines.HighDefinition.Editor` becomes `Unity.RenderPipe~45d4eb49`. The path is now 285 characters.
+2. The generator folder `Unity.UIToolkit.SourceGenerator` becomes `Unity.UIToolkit.~b9605758`: 279 characters.
+3. The file name is cut to the 77 characters left: `UnityEditor.Rendering.HighDefinition.Compositor.CompositionLaye~f7565493.g.cs`. The path is now exactly 259 characters.
+
+```text
+Library/GeneratedCodeDump/Unity.RenderPipe~45d4eb49/Unity.UIToolkit.~b9605758/UnityEditor.Rendering.HighDefinition.Compositor.CompositionLaye~f7565493.g.cs
+```
+
+A shortened name like these is a *cut name*: the start of the name, then the short hash of the full name, then, for a file, its `.g.cs` or `.generated.cs` ending.
+
+### The limits
+
+| OS | Whole file path | Folder path | One name | Counted in |
+| --- | --- | --- | --- | --- |
+| Windows | 259 | 247 | 255 | UTF-16 characters |
+| macOS, Linux | 1023 | 1023 | 255 | UTF-8 bytes |
+
+The whole path counts, from the drive or the root, with the project's own path included.
+
+### The cut order
+
+Names stay whole wherever the full path fits. When a path does not fit, the dump cuts names in this order until it does:
+
+1. The assembly folder becomes its first 16 characters plus the short hash of its full name. This applies to all of that assembly's files.
+2. Then a generator folder is cut the same way, for all of that folder's files.
+3. Then each file that still does not fit is cut to the room left: as much of its start as fits, the short hash of its full name, and its ending. `.generated.cs` or `.g.cs` (else the extension) stays whole.
+4. A file that still does not fit, because fewer than 8 characters of its start would remain, is skipped with a warning.
+
+A folder name of 25 characters or fewer is never cut, since its cut name would be no shorter. A folder can switch between its full name and its cut name when the longest path inside it changes. Each dump deletes the other form, so only one of them exists.
+
+The short hash keeps a cut name the same from one dump to the next. The `.work/<Assembly>/` folder is cut the same way when its `replay.rsp` or `errors.sarif` would be over the limit.
+
+### Finding a cut file
+
+A cut name loses part of the type name, but the header lines always hold the full names. So search the header instead of the file names:
+
+```bash
+grep -rl --exclude-dir=.work "Hint: .*ExampleBehaviour" Library/GeneratedCodeDump
+grep -rl --exclude-dir=.work "Assembly: Assembly-CSharp" Library/GeneratedCodeDump
+```
+
+### Skipped files
+
+A file that cannot fit even with every cut is left out, and the Console shows:
+
+```text
+[Generated Code Dump] <Assembly>: <N> files skipped: their path is over the <limit>-character limit of this OS; move the project to a shorter path.
+```
+
+The skipped paths follow, one per line. `<limit>` is 259 on Windows and 1023 on macOS and Linux, where it counts UTF-8 bytes although the message says "character". The fix is the one the message gives: move the project to a shorter path.
+
+The dump does not rely on Windows' long-path support. It keeps every path within the limits above. If the project path is too deep for that, some files are skipped with this warning.
+
+## Batch mode and CI
+
+This runs Unity once without a window, dumps everything and lists the result:
+
+```bash
+PROJECT=/path/to/project
+UNITY=~/Unity/Hub/Editor/6000.0.65f1/Editor/Unity   # your Unity Editor binary
+
+mkdir -p "$PROJECT/UserSettings"
+printf '{"enabled": true}\n' > "$PROJECT/UserSettings/GeneratedCodeDumpSettings.json"
+
+"$UNITY" -batchmode -nographics -projectPath "$PROJECT" -quit -logFile unity.log
+grep '\[Generated Code Dump\]' unity.log
+ls "$PROJECT/Library/GeneratedCodeDump"
+```
+
+With the dump on, a `-batchmode` Editor start runs a full dump and waits until it is complete before it goes on. A CI job or an agent can therefore read the dump as soon as the Editor exits after `-quit`.
+
+In batch mode there is no background thread. The Editor's own thread starts the compilers and waits for them. Every dump in a batch run waits like this, including a per-compile dump after the run compiles scripts, until a wait runs out (below).
+
+Any batch run while the dump is on does the same full dump when it starts: `-runTests`, a build, or any other. The settings file is the only switch. Delete it after the run if later batch runs on that machine should skip the dump.
+
+### How long it waits
+
+The wait is at most 300 seconds per round, where a round is as many assemblies as compile at once. With 11 assemblies and 6 compiling at once, that is 2 rounds, so at most 600 seconds.
+
+Past that limit the Editor logs a warning and carries on:
+
+```text
+[Generated Code Dump] stopped waiting after <seconds> s; the rest of the dump finishes in the next Editor session.
+```
+
+The unfinished jobs stay in `Library/GeneratedCodeDump/.work/jobs.txt`, and the next Editor session dumps the remaining assemblies. After giving up once, the rest of that batch run no longer waits for dumps.
+
+A single compiler that runs for more than 300 seconds, counted from its start, is stopped and its output is ignored. This applies in the Editor too, and it logs:
+
+```text
+[Generated Code Dump] <Assembly>: the compiler ran for over 300 s, so it was stopped and its output is ignored.
+```
+
+To check that a run finished the dump, look for leftover jobs:
+
+```bash
+grep -q '^job' "$PROJECT/Library/GeneratedCodeDump/.work/jobs.txt" && echo "dump incomplete" || echo "dump complete"
+```
+
+The full walkthrough is in [Dump in batch mode](examples/dump-in-batch-mode.md).
+
+## Performance
+
+At most half the logical CPUs run a compiler at once, and never fewer than 1 or more than 8. A machine with 12 logical CPUs runs 6 at once; one with 2 runs 1; one with 32 runs 8. The Preferences page and the `queued` log line show the number.
+
+Each replay is a separate compiler process. In the Editor, a background thread starts them and collects their output every 250 milliseconds. The Editor never waits for them, and the dump keeps going while the Editor is in the background.
+
+No replay starts while Unity itself is compiling. Queued replays wait until Unity's compile ends.
+
+Measured on this package's repository, with 12 logical CPUs (so 6 at once): a full dump queued 11 assemblies and never ran more than 6 compilers. Compiling took about 1.7 seconds of a 7.5-second batch run, which also covered Editor start, import and quit.
+
+A full dump costs about one compile per assembly that loads an analyzer. Unity's own generator runs on most assemblies, so a large project's full dump grows with its assembly count. A per-compile dump replays only the assemblies rebuilt by that compile.
+
+## Warnings and failures
+
+Here is what the Console shows when Unity's compiler is not where the dump expects it after a compile:
+
+```text
+[Generated Code Dump] Unity's C# compiler was not found at <path>. The dump is off until the next domain reload.
+```
+
+Every message the dump logs starts with `[Generated Code Dump]`. Every failure is a Console warning, never an error. The dump never breaks the project's compile: its failures stay warnings, and it never writes Unity's own outputs.
+
+### Warnings that only warn
+
+Most failures only log a warning, and the dump carries on. A failed replay and a failed Dump Now are both of this kind. When a replay cannot run or is stopped, the assembly's folder keeps the files from the previous dump.
+
+Within one replay, paths over the limit and other file errors are reported as two separate warnings. Each names the files it is about.
+
+### Warnings that also turn the dump off
+
+A few failures also turn the dump off until the next domain reload. Their warning ends with `The dump is off until the next domain reload.` These are:
+
+- a failure while the dump starts up, at Editor start or after a domain reload;
+- a failure while checking the setting;
+- a failure while handling Unity's compile events;
+- Unity's compiler missing after a compile.
+
+This does not change the settings file: the switch stays on. The next domain reload, which follows every compile, turns the dump back on and tries again. If the cause is still there, it warns again.
+
+### After a Unity update
+
+The dump relies on Unity internals, not public API: the response files Unity writes under `Library/Bee/`, and the compiler and .NET runtime inside the Editor install (see [How it works](#how-it-works)). A Unity update can move or change any of them.
+
+If that happens, the dump logs a warning and stops: after a compile it is off until the next domain reload, as above, and Dump Now queues nothing. Your project still compiles as usual, and the files already in `Library/GeneratedCodeDump/` stay as they were.
+
+### Messages
+
+Each message below follows the `[Generated Code Dump] ` prefix.
+
+| Message | What happened | What the dump does |
+| --- | --- | --- |
+| `<full path> is not valid: expected {"enabled": true} or false. The dump is off.` | The settings file is not valid JSON of the expected shape. | Stays off until the file is fixed. Warns again only when the file changes and is still invalid. |
+| `<Assembly>: <N> files skipped: their path is over the <limit>-character limit of this OS; move the project to a shorter path.` | Some paths are too long even with every cut. See [Long paths](#long-paths). | Skips those files; the rest are written. |
+| `<Assembly>: <N> files could not be replaced, most likely open in another program; they keep their older 'Dumped:' line and the next dump retries.` | Some files could not be written or deleted, usually because another program holds them open. | Keeps the older files; the next dump tries again. |
+| `<Assembly>: the compiler ran for over 300 s, so it was stopped and its output is ignored.` | One replay took more than 300 seconds. | Keeps the assembly's previous files. |
+| `<Assembly>: the compiler stopped before writing errors.sarif, so the previous dump is kept. Its arguments: Library/GeneratedCodeDump/.work/<Assembly>/replay.rsp` | The replay's compiler crashed or was stopped. | Keeps the assembly's previous files. |
+| `<Assembly>: the replay reported compile errors, so the dump can be incomplete. See Library/GeneratedCodeDump/.work/<Assembly>/errors.sarif` | The replayed compile had errors. | Writes what the generators produced anyway. |
+| `stopped waiting after <seconds> s; the rest of the dump finishes in the next Editor session.` | A batch run reached its wait limit. See [Batch mode and CI](#batch-mode-and-ci). | Leaves the rest to the next Editor session. |
+| `Unity's C# compiler was not found at <path>.` | The compiler is missing from the Editor install. | Queues nothing. After a compile, also turns the dump off until the next domain reload. |
+| `Unity's .NET runtime was not found at <path>.` | The runtime the compiler needs is missing. | The same as a missing compiler. |
+| `Unity's build folder Library/Bee/artifacts was not found.` | Unity has not compiled this project yet, or its layout changed. | The same as a missing compiler. |
+| `UserSettings/GeneratedCodeDumpSettings.json could not be written: <reason>` | The menu or Preferences toggle could not save the setting. | Leaves the setting as it was. |
+| `watching UserSettings/GeneratedCodeDumpSettings.json failed: <reason> An edit to it made outside the Editor now applies on the next compile.` | The Editor could not watch the settings file. | Picks up file edits at the next compile instead of within a second. |
+| `the background dump stopped: <reason> It restarts with the next dump.` | The Editor's background thread hit an error. | Starts again with the next dump request. |
+
+The messages from the upgrade are listed in [Upgrading from 1.0.0](#upgrading-from-100).
+
+## Upgrading from 1.0.0
+
+1.0.0 kept its switch and its dump in `Library/com.elestrago.unity.generated-code-dump/`, with namespace folders in the dump. Its temporary output went to `<temp>/GCDump/<project hash>/`, where `<temp>` is the system temp folder and `<project hash>` the short hash of the project's root path, without the `~`.
+
+The upgrade runs at every Editor start, batch mode included, before the setting is first read. The first start with this version does the work:
+
+1. `Library/com.elestrago.unity.generated-code-dump/Settings.json` moves unchanged to `UserSettings/GeneratedCodeDumpSettings.json`, unless that file already exists. If it does, the new file wins.
+2. The rest of the old folder is deleted. The folder is kept while its setting could not be moved.
+3. This project's old temp folder `<temp>/GCDump/<project hash>/` is deleted, and `<temp>/GCDump/` too once it is empty. Other projects still on 1.0.0 may use it until then.
+
+When the old folder is gone, the Console shows:
+
+```text
+[Generated Code Dump] Library/com.elestrago.unity.generated-code-dump/ is replaced by Library/GeneratedCodeDump/ and UserSettings/GeneratedCodeDumpSettings.json, so it was deleted.
+```
+
+A step that fails logs a warning, most of them ending `The next Editor start retries.`, and is tried again at the next start. It never turns the dump off.
+
+If the dump is on, that same start then runs a full dump into `Library/GeneratedCodeDump/`. Scripts that read the 1.0.0 paths must switch to the flat layout in [Reading the output](#reading-the-output).
+
+Moving a setting that is off writes the new settings file while the dump is off.
+
+## How it works
+
+Each replay goes through these steps:
+
+1. Unity's compile writes a *response file* for each assembly: a text file with the compiler arguments for that assembly, one per line, covering sources, references, analyzers and outputs. It sits at `Library/Bee/artifacts/<hash>.dag/<Assembly>.rsp`, sometimes with an `<Assembly>.rsp2` whose arguments come after it.
+2. The `<hash>.dag` folder is a *build graph*, Unity's record of a compile. Older build graphs can sit beside the latest one, so the newest response file wins, and a full dump takes its assemblies from the newest build graph.
+3. Only an assembly whose response file has at least one `-analyzer:` argument is replayed.
+4. The dump copies the arguments and drops every one that writes a file: `-out`, `-refout`, `-doc`, `-pdb`, `-errorlog` and `-generatedfilesout`. It adds its own `-out`, `-refout`, `-errorlog` and `-generatedfilesout`, and saves the result as `Library/GeneratedCodeDump/.work/<Assembly>/replay.rsp`.
+5. It runs the Roslyn compiler that ships inside the Unity Editor install: `DotNetSdkRoslyn/csc.dll`, run on `NetCoreRuntime/dotnet`. Both are in the Editor's contents folder: `Editor/Data/` on Windows and Linux, `Unity.app/Contents/` on macOS.
+6. When the compiler exits, the generated files are named by the rules in [Reading the output](#reading-the-output), given their header lines, and synced into `Library/GeneratedCodeDump/<Assembly>/`. Then the job's temp folder is deleted.
+
+The new outputs in step 4 go here:
+
+| Argument | Points at |
+| --- | --- |
+| `-generatedfilesout` | `<temp>/GenDump/<project hash>/<job id>/g/`, the generated files |
+| `-out`, `-refout` | `<Assembly>.dll` and `<Assembly>.ref.dll` in `<temp>/GenDump/<project hash>/<job id>/o/` |
+| `-errorlog` | `Library/GeneratedCodeDump/.work/<Assembly>/errors.sarif` |
+
+The DLL keeps the assembly's name because the compiler takes the assembly name from that file name. `<project hash>` is the short hash of the project's root path, without the `~`. It keeps the temp path short wherever the project lives.
+
+Unity's own outputs are never touched: the dump only reads the response files. The jobs are recorded in `.work/jobs.txt`, so a dump cut short by a domain reload or an Editor restart resumes.
+
+## Internals
+
+For contributors. Every identifier, source file and API link lives in this section.
+
+- Package name: `com.elestrago.unity.generated-code-dump`.
+- Package source: `Assets/Package/GeneratedCodeDump`.
+- Source files: `Assets/Package/GeneratedCodeDump/Editor/`.
+- `file:line` pointers for every type are in the [API reference](api.md).
+
+### Assembly
+
+| Assembly | Root namespace | Platforms | References | asmdef |
+| --- | --- | --- | --- | --- |
+| `GeneratedCodeDump.Editor` | `GeneratedCodeDump.Editor` | Editor | none | `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDump.Editor.asmdef` |
+
+- Every type is `internal`, in the one namespace `GeneratedCodeDump.Editor`.
+- `AssemblyInfo.cs` holds `InternalsVisibleTo("GeneratedCodeDump.Editor.Tests")` for the test assembly.
+- Extension points: none. No type is abstract, virtual, `Base`-suffixed or `partial`.
+- No `[CreateAssetMenu]`, and no public static method on a public type.
+- No `ScriptableObject` or `[Serializable]` type. All state is plain files: the switch in `UserSettings/`, the dump and `.work/` in `Library/GeneratedCodeDump/`, one temp folder per job.
+- UnityEditor is used only by `GeneratedCodeDumper.cs`, `GeneratedCodeDumpSettingsProvider.cs` and `GeneratedCodeMenuItems.cs`.
+- `GeneratedCodeDumpFinisher`, `GeneratedCodeDumpSettingsWatcher`, `GeneratedCodeDumpSettings` and `GeneratedCodeDumpMigration` use `UnityEngine.Debug` for warnings; `GeneratedCodeDumpPaths` reads `Application.dataPath` once.
+
+### Source files
+
+| File | Role | API |
+| --- | --- | --- |
+| `GeneratedCodeDumper.cs` | `[InitializeOnLoad]` entry. Compile hooks, `DumpIfJustEnabled`, `DumpAll`, `SetEnabled`, `Enqueue`, `StartReplay`, finishing jobs, batch-mode wait (`FinishAllBlocking`, `BatchWaitSeconds`), `MarkUnavailable`. Holds `MaxConcurrent`, `JobTimeoutSeconds` (300), `StampFormat`, `SessionLock`, `Gate`. | [GeneratedCodeDumper](api.md#generatedcodedumper) |
+| `GeneratedCodeDumpFinisher.cs` | Background thread `Generated code dump`: `GeneratedCodeDumper.Tick` every 250 ms while jobs exist. Stopped before each domain reload and on quit, joining for up to 2 s. Not used in batch mode. | [GeneratedCodeDumpFinisher](api.md#generatedcodedumpfinisher) |
+| `GeneratedCodeDumpJobs.cs` | Job store `.work/jobs.txt`: pure `Format` / `Parse`, `Read` / `Write` under a file lock. Ids only go up, across restarts. | [GeneratedCodeDumpJobs](api.md#generatedcodedumpjobs), [GeneratedCodeDumpJob](api.md#generatedcodedumpjob), [GeneratedCodeDumpJobList](api.md#generatedcodedumpjoblist), [GeneratedCodeDumpJobState](api.md#generatedcodedumpjobstate) |
+| `GeneratedCodeDumpSession.cs` | Session marker `.work/enabled-session` and the pure `ShouldDumpAll`. | [GeneratedCodeDumpSession](api.md#generatedcodedumpsession) |
+| `GeneratedCodeDumpSettings.cs` | The switch. Thread-safe, re-read when the file's write time or length changes, atomic write, one warning per invalid version of the file. | [GeneratedCodeDumpSettings](api.md#generatedcodedumpsettings) |
+| `GeneratedCodeDumpSettingsFile.cs` | Strict flat-JSON `Format` / `TryParse` of the settings file, no `JsonUtility`, so the watcher can read it off the main thread. | [GeneratedCodeDumpSettingsFile](api.md#generatedcodedumpsettingsfile) |
+| `GeneratedCodeDumpSettingsWatcher.cs` | `FileSystemWatcher` with a 300 ms debounce after the last change, calling `DumpIfJustEnabled`. Watches `UserSettings/` for the file, or the project root for `UserSettings/` while it is missing (pure `Target`). Not used in batch mode. | [GeneratedCodeDumpSettingsWatcher](api.md#generatedcodedumpsettingswatcher) |
+| `GeneratedCodeDumpMigration.cs` | 1.0.0 upgrade, run before the setting is first read. Pure `ShouldMoveSettings`; `Migrate` takes full paths. A failure is a warning, never `MarkUnavailable`. | [GeneratedCodeDumpMigration](api.md#generatedcodedumpmigration) |
+| `GeneratedCodeDumpRsp.cs` | `Find` (newest `<Assembly>.rsp`), `ReadArguments` (plus `.rsp2`), `ListAssemblies` (the newest build graph, `.mvfrm.rsp` excluded). | [GeneratedCodeDumpRsp](api.md#generatedcodedumprsp) |
+| `GeneratedCodeDumpArgs.cs` | `HasAnalyzer` (`-analyzer:` or `/analyzer:`, any case, non-empty value) and `Rewrite` (drops every output argument, appends the replay's own). | [GeneratedCodeDumpArgs](api.md#generatedcodedumpargs) |
+| `GeneratedCodeDumpOutput.cs` | Compiler output to the flat layout (`Entries`, with the collision tag), the cut plan (`Plan`), header lines (`Header`, `Stamp`), per-file `Sync` that also removes the assembly folder's other form. | [GeneratedCodeDumpOutput](api.md#generatedcodedumpoutput), [GeneratedCodeDumpEntry](api.md#generatedcodedumpentry), [GeneratedCodeDumpLayout](api.md#generatedcodedumplayout), [GeneratedCodeDumpSyncResult](api.md#generatedcodedumpsyncresult) |
+| `GeneratedCodeDumpNames.cs` | `Tag` (`~<fnv8>`), `CutFolder`, `CutFile` (null below 8 start characters), `Suffix`, `SafeSegment`. Constants `MaxUncutLength` 25, `CutFolderStart` 16, `MinCutFileStart` 8. | [GeneratedCodeDumpNames](api.md#generatedcodedumpnames) |
+| `GeneratedCodeDumpPathBudget.cs` | Per-OS limits `Windows`, `Unix`, `Current`; `Length`, `Fits`. Passed in so tests use small budgets. No Unity API. | [GeneratedCodeDumpPathBudget](api.md#generatedcodedumppathbudget) |
+| `GeneratedCodeDumpPaths.cs` | Every path, project-relative constants, the 1.0.0 ones as `Legacy*`, the `.work/<Assembly>/` cut (`WorkDirectory`), the temp folder keyed by `Fnv1a` of the project root. | [GeneratedCodeDumpPaths](api.md#generatedcodedumppaths) |
+| `GeneratedCodeDumpIdentity.cs` | Every shown name: `PackageName`, `LibraryFolderName`, `LogPrefix`, `ThreadName`, `ScratchFolderName` (`GenDump`), `LegacyScratchFolderName` (`GCDump`), `MenuRoot`, `SettingsPath`. | [GeneratedCodeDumpIdentity](api.md#generatedcodedumpidentity) |
+| `GeneratedCodeDumpProcess.cs` | Process identity by pid and start time (2 s tolerance, unknown start matches any): `IsRunning`, `TryKill`, the current Editor's id and start. | [GeneratedCodeDumpProcess](api.md#generatedcodedumpprocess) |
+| `GeneratedCodeDumpFiles.cs` | `WriteAtomic` (`<path>.tmp`, then replace), `ReadTextOrNull`, `CreateHiddenDirectory` (Hidden `.work` on Windows), folder cleanup. | [GeneratedCodeDumpFiles](api.md#generatedcodedumpfiles) |
+| `GeneratedCodeDumpSettingsProvider.cs` | The `Preferences/Generated Code Dump` page, user scope. | [GeneratedCodeDumpSettingsProvider](api.md#generatedcodedumpsettingsprovider) |
+| `GeneratedCodeMenuItems.cs` | The `Tools/Generated Code Dump/` menu. | [GeneratedCodeMenuItems](api.md#generatedcodemenuitems) |
+| `AssemblyInfo.cs` | `InternalsVisibleTo` for `GeneratedCodeDump.Editor.Tests`. | none |
+
+### Entry points
+
+Menu items (`GeneratedCodeMenuItems`):
+
+| Menu item | Priority | Method | Calls |
+| --- | --- | --- | --- |
+| `Tools/Generated Code Dump/Enabled` | 100 | `ToggleEnabled` | `GeneratedCodeDumper.SetEnabled(!IsEnabled)`; checkmark from the validator `ValidateEnabled` |
+| `Tools/Generated Code Dump/Dump Now` | 111 | `DumpNow` | `GeneratedCodeDumper.DumpAll`, whatever the setting |
+| `Tools/Generated Code Dump/Open Folder` | 112 | `OpenFolder` | `Directory.CreateDirectory`, then `EditorUtility.OpenWithDefaultApp` |
+| `Tools/Generated Code Dump/Preferences…` | 123 | `OpenSettings` | `SettingsService.OpenUserPreferences("Preferences/Generated Code Dump")` |
+
+Preferences page:
+
+- `[SettingsProvider]` factory `GeneratedCodeDumpSettingsProvider.Create`, `SettingsScope.User`, path `Preferences/Generated Code Dump`.
+- Search keywords: `Generated`, `Source Generator`, `Roslyn`, `Dump`.
+
+Start-up (the `[InitializeOnLoad]` static constructor of `GeneratedCodeDumper`):
+
+1. Return at once in an asset import worker (`AssetDatabase.IsAssetImportWorkerProcess`).
+2. `CaptureMainThreadState`: project root, temp root, settings, current process, `Application.isBatchMode`, and the compiler paths from `EditorApplication.applicationContentsPath`.
+3. `GeneratedCodeDumpMigration.Run`.
+4. Hook `CompilationPipeline.compilationStarted`, `CompilationPipeline.assemblyCompilationFinished`, `CompilationPipeline.compilationFinished`, `AssemblyReloadEvents.beforeAssemblyReload` and `EditorApplication.quitting`. The last two call `Shutdown`: the finisher first, then the watcher.
+5. Start `GeneratedCodeDumpSettingsWatcher`, except in batch mode.
+6. `DumpIfJustEnabled`.
+7. If `jobs.txt` holds jobs left by the previous domain or Editor, `Kick`: start the finisher, or `FinishAllBlocking` in batch mode.
+8. Any exception: `MarkUnavailable`.
+
+Compile hooks:
+
+- `compilationStarted`: sets `_compiling`, so `StartQueued` starts no compiler until Unity's compile ends.
+- `assemblyCompilationFinished`: while on, records the assembly unless a message has type `Error`.
+- `compilationFinished`: clears `_compiling`; while on, `TryLocateCompiler` (else `MarkUnavailable`), then `Enqueue` and `Kick`.
+
+`DumpIfJustEnabled` (holds `SessionLock`):
+
+- Off: if the session marker exists, delete it and `DropQueued` (queued jobs removed, reruns cleared).
+- On: write the marker unless it names this process; then `ShouldDumpAll(enabled, markerIsThisProcess, rootExists)`, true when on and either the marker was not this process's or the dump folder is missing, runs `DumpAll`.
+- `DumpAll` and `Enqueue` create `Library/GeneratedCodeDump/` even when nothing is queued, so a project without analyzers does not run a full dump on every reload.
+- `DumpAll` with the compiler or `Library/Bee/artifacts` missing: one warning, returns 0, no `MarkUnavailable`.
+
+### File formats
+
+- `UserSettings/GeneratedCodeDumpSettings.json`:
+  - written by `GeneratedCodeDumpSettingsFile.Format` as `{`, `    "enabled": true`, `}` on three lines, UTF-8 without BOM, through `WriteAtomic`;
+  - parsed by `TryParse`: one flat object, string keys, values string, number, `true`, `false` or `null`; `enabled` exactly `true` or `false`; missing `enabled` means off; a leading BOM is allowed.
+- `.work/jobs.txt`: a `next <id>` line, then one line per job, sorted by id, with 8 tab-separated fields:
+
+  | # | Field | Values |
+  | --- | --- | --- |
+  | 1 | tag | `job` |
+  | 2 | id | 1 or more; ids only go up, so a new job never reuses an old temp folder |
+  | 3 | state | `queued` or `running` |
+  | 4 | rerun | `0` or `1` |
+  | 5 | process id | the compiler's pid, `0` while queued |
+  | 6 | process start ticks | the compiler's start time, UTC ticks |
+  | 7 | started ticks | when the job started its compiler, UTC ticks: the timeout counts from it and it is the `Dumped:` time |
+  | 8 | assembly | the assembly name |
+
+  `Parse` skips a malformed line and a second job with an id or assembly already seen; `next` always ends above the highest job id.
+- `.work/enabled-session`: `<process id> <start ticks>` and a newline, for the Editor that last found the dump on. A missing start time reads as 0 (unknown) and matches any process start.
+- `.work/<Assembly>/`: only `replay.rsp` (UTF-8 without BOM) and `errors.sarif` of the last replay. It is deleted and created again when a replay starts. Its name is `SafeSegment(assembly)`, or `CutFolder(assembly)` when either file would be over the budget.
+- `<temp>/GenDump/<fnv8 of the project root>/<job id>/`:
+  - `g/`: the compiler's `-generatedfilesout`, laid out as `<GeneratorAssembly>/<GeneratorType>/<hint>`;
+  - `o/`: `<Assembly>.dll` and `<Assembly>.ref.dll`;
+  - deleted after each job. The project folder is deleted whole when jobs are added to an empty list (a crash's leftovers), and `<temp>/GenDump/` once it is empty.
+- 1.0.0 paths: `LegacyRoot` (`Library/com.elestrago.unity.generated-code-dump/`), `LegacySettingsFile` (its `Settings.json`), `LegacyScratchBase` (`<temp>/GCDump/`), `LegacyScratchRoot` (this project's folder in it).
+
+### Jobs in memory
+
+- Type: `GeneratedCodeDumpJob`, one per line of `jobs.txt`.
+- Held in: `GeneratedCodeDumpJobList`, with `NextId` (starts at 1).
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `Id` | `long` | Job id |
+| `Assembly` | `string` | Assembly name |
+| `State` | `GeneratedCodeDumpJobState` | `Queued` or `Running` |
+| `ProcessId` | `int` | Compiler pid |
+| `ProcessStartUtcTicks` | `long` | Compiler process start time |
+| `StartedUtcTicks` | `long` | When the job started its compiler: the timeout counts from it, and it is the `Dumped:` time |
+| `Rerun` | `bool` | A dump was asked while the compiler ran |
+
+- `GeneratedCodeDumpJobList.DropNotStarted` removes queued jobs and clears every `Rerun`.
+- `Enqueue` per assembly: no job adds a queued one; a running job gets `Rerun = true`; a queued job is left alone, since it reads the response file when it starts.
+
+### Threading and locks
+
+- No Unity API off the main thread. The static constructor caches the project root, the compiler paths and the batch-mode flag.
+- Threads: the main thread runs the hooks, the menu and the Preferences page; the finisher thread runs `Tick`; the watcher's debounce timer calls back on a thread-pool thread. Batch mode uses the main thread only.
+- Lock order, outermost first:
+  1. the settings watcher's `CallbackLock`;
+  2. `GeneratedCodeDumper.SessionLock`;
+  3. `GeneratedCodeDumper.Gate`;
+  4. the finisher's `ThreadLock`;
+  5. the job store's `FileLock`.
+- The watcher's own `Sync` lock is held only briefly and never while calling out.
+- Every read-modify-write of the jobs holds `Gate`; `Read` and `Write` also take `FileLock`.
+- `StartQueued`: nothing while `_compiling`; starts jobs in id order while fewer than `MaxConcurrent` live compilers run, and writes `jobs.txt` after each start, so a reload never starts a second compiler for a job. A stopping finisher starts nothing.
+- Compiler process: `dotnet exec csc.dll /nostdlib /noconfig -nologo @replay.rsp`, working directory the project root, `UseShellExecute = false`, `CreateNoWindow`, no redirected output (an unread pipe dies with the domain and can take the compiler with it).
+- Finishing (`FinishExited`), per exited job, in this order:
+  1. `SyncOutput` syncs the files, unless `Rerun` is set;
+  2. `Complete` removes the job, re-reading under `Gate`, and queues the assembly again under a new id when `Rerun` is set;
+  3. the job's temp folder is deleted.
+
+  Removing the job last means a domain reload mid-finish repeats the finish.
+- Timeout: a running job past `JobTimeoutSeconds` is killed (`TryKill` checks pid and start time) and completed without a sync.
+- `SyncOutput`: no `errors.sarif` keeps the previous dump; an `"level": "error"` entry warns but still syncs.
+- `Sync` tries every listing, write and delete on its own. `PathTooLongException` goes to `TooLong`, any other I/O or access error to `Failed`, and each list gets its own warning.
+- Batch mode: `Kick` calls `FinishAllBlocking`, which runs `Tick` every 50 ms until no job is left or `BatchWaitSeconds(jobs, MaxConcurrent, 300)` (300 × ceil(jobs / `MaxConcurrent`)) runs out. After giving up it does not wait again in that domain.
+
+### Preferences page
+
+- IMGUI: a user-scope `SettingsProvider` drawn with `EditorGUILayout` in `OnGUI`. The package has no `.uxml` or `.uss` file and no `EditorWindow`, `PropertyDrawer` or custom inspector.
+- Top to bottom:
+  1. a help box on what the dump does and where it writes;
+  2. the `Dump generated code` toggle, which calls `GeneratedCodeDumper.SetEnabled`;
+  3. an info box: where the setting lives, that an edit applies within a second and batch mode follows it, and the `MaxConcurrent` number;
+  4. an `Output` section with `Folder` `Library/GeneratedCodeDump/`;
+  5. `Open Folder` and `Dump Now` buttons, which call `GeneratedCodeMenuItems.OpenFolder` and `GeneratedCodeMenuItems.DumpNow`.
+- The help texts describe a full dump more broadly than the code runs it: only assemblies whose compile loads an analyzer are replayed.

package/Editor/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("GeneratedCodeDump.Editor.Tests")]

package/Editor/AssemblyInfo.cs.meta

@@ -0,0 +1,2 @@
+fileFormatVersion: 2
+guid: fbbf082de05732428bb727f1d0428801