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

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+---
+
+## [1.0.0](https://gitlab.com/elestrago-pkg/generated-code-dump/-/tags/1.0.0)
+
+### Added
+
+- Added a dump of every Roslyn source generator's output to `Library/GeneratedCodeDump/` after each compile. See `README.md`.
+- Added `Dumped:`, `Assembly:`, `Generator:` and `Hint:` header lines to every dumped file. See `Documentation~/manual.md`.
+- Added short-hash name cutting so every dump path fits the OS path limit. See `Documentation~/manual.md`.
+- Added the per-user switch in `Preferences/Generated Code Dump`, `Tools/Generated Code Dump/Enabled` and `UserSettings/GeneratedCodeDumpSettings.json`. See `Documentation~/examples/turn-on-the-dump.md`.
+- Added `Tools/Generated Code Dump/Dump Now` and `Open Folder` menu items. See `Documentation~/examples/dump-now.md`.
+- Added a blocking full dump when a batch-mode Editor starts with the dump on. See `Documentation~/examples/dump-in-batch-mode.md`.
+
+---

package/CHANGELOG.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 17de4d04be6d431e0bd1d019af2701d5
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

package/Documentation~/api.md

@@ -0,0 +1,583 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+<!-- unity-package-docs: scanner=2.0.2; api-render=2 -->
+
+# Generated Code Dump — API Reference
+
+Comprehensive reference for every public/internal type and member. Generated from source; do not edit by hand.
+
+## Contents
+
+- [`GeneratedCodeDump.Editor`](#generatedcodedumpeditor)
+
+## `GeneratedCodeDump.Editor`
+
+### GeneratedCodeDumpArgs
+
+```csharp
+internal static class GeneratedCodeDumpArgs
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpArgs.cs:10` (md5: `e75a0a6ba274cff0c5f8d1240dadc7f0`, lines: 113)
+
+Reads and rewrites a Unity compiler response file (one argument per line) so it can be replayed with generated-files output, without overwriting any of Unity's own outputs. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | HasAnalyzer | `internal static bool HasAnalyzer(IEnumerable<string> lines)` | 29 | True when the compilation loads at least one analyzer (`-analyzer:` or `/analyzer:`, any case). Without one no source generator runs, so a replay could produce nothing. |
+| method | Rewrite | `internal static List<string> Rewrite(IEnumerable<string> lines, string outDll, string refDll, string generatedDir, string errorLog)` | 45 | Drops every output-writing argument (both '-' and '/' prefixes, any case) and appends `-out`, `-refout`, `-generatedfilesout` and `-errorlog` with quoted paths. Every other line is kept unchanged and in order. |
+
+### GeneratedCodeDumpEntry
+
+```csharp
+internal sealed class GeneratedCodeDumpEntry
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpOutput.cs:12` (md5: `0acc716509ba2c9af0a56aa2cd27cd8c`, lines: 449)
+
+One file of the compiler's generated-files output and its dump name before any cut.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Source | `internal string Source` | 18 | Path under the generated-files output, '/'-separated: `<GeneratorAssembly>/<GeneratorType>/<hint name>`. |
+| field | GeneratorAssembly | `internal string GeneratorAssembly` | 23 | The generator's assembly name; null for a file fewer than two folders deep. |
+| field | GeneratorType | `internal string GeneratorType` | 28 | The generator's full type name; null for a file fewer than two folders deep. |
+| field | Hint | `internal string Hint` | 33 | The hint name as the generator gave it; `Source` when no generator is known. |
+| field | GeneratorFolder | `internal string GeneratorFolder` | 38 | The generator's folder with its full, safe name; null when no generator is known. |
+| field | Name | `internal string Name` | 44 | Path under `GeneratorFolder` (else under the assembly folder), '/'-separated and safe. Its last part is the file name. |
+| property | FullPath | `internal string FullPath { get; }` | 49 | Path under the assembly folder with full names. |
+
+### GeneratedCodeDumper
+
+```csharp
+internal static class GeneratedCodeDumper
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumper.cs:47` (md5: `a25cc70f77709d7c8c36041c75f505ed`, lines: 689)  
+**Attributes:** `[InitializeOnLoad]`
+
+After each compile, replays Unity's compiler response file of every rebuilt assembly that loads an analyzer, with `-generatedfilesout`, so the files every source generator produced land in `Library/GeneratedCodeDump/<Assembly>/<GeneratorAssembly>/`. The replay writes its assemblies to the job's temp folder and never touches Unity's own Library/Bee outputs.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | MaxConcurrent | `internal static readonly int MaxConcurrent` | 56 | Compilers that may run at once: half the logical processors, between 1 and 8. |
+| method | DumpIfJustEnabled | `internal static void DumpIfJustEnabled()` | 112 | Dumps everything when the dump has just turned on — Editor start, or the setting switched on in Preferences, the menu or its file — or when its output folder is missing, so the folder is never stale or absent while the dump is on. Turning it off drops the jobs that have not started. Safe on any thread. |
+| method | DumpAll | `internal static int DumpAll()` | 160 | Queues every assembly of the newest build graph that loads an analyzer, whatever the setting. Returns how many were queued. Safe on any thread. |
+| method | SetEnabled | `internal static void SetEnabled(bool enabled)` | 194 | Saves the setting and acts on it at once. Main thread (Preferences page and menu). |
+| method | Tick | `internal static void Tick()` | 213 | One round of the finisher: moves the output of every exited replay into the dump, then starts queued jobs while fewer than `MaxConcurrent` compilers run. |
+| method | HasJobs | `internal static bool HasJobs()` | 219 |  |
+| method | BatchWaitSeconds | `internal static double BatchWaitSeconds(int jobs, int maxConcurrent, double jobTimeoutSeconds)` | 228 | How long batch mode waits for `jobs` jobs: every job may take the full timeout, and `maxConcurrent` of them run at once. |
+
+### GeneratedCodeDumpFiles
+
+```csharp
+internal static class GeneratedCodeDumpFiles
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpFiles.cs:12` (md5: `9bb31041be2e5656ca9fe700a7873518`, lines: 120)
+
+File helpers shared by the dump's state files (settings, jobs, session marker) and its work folders. No UnityEditor use, so every thread can call them.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Utf8NoBom | `internal static readonly Encoding Utf8NoBom` | 14 |  |
+| method | WriteAtomic | `internal static void WriteAtomic(string path, string text)` | 20 | Writes `text` to `<path>.tmp`, then moves it over `path`, so a reader, or an Editor that stops mid-write, never sees half a file. Creates the folder. |
+| method | ReadTextOrNull | `internal static string ReadTextOrNull(string path)` | 42 | The file's text, or null when it does not exist. Any other failure throws, so a caller never takes a file it could not read for an empty one. |
+| method | CreateHiddenDirectory | `internal static void CreateHiddenDirectory(string path)` | 58 | Creates the folder and, on Windows, marks it Hidden, so Explorer lists only what sits next to it. Failing to mark it is ignored. |
+| method | DeleteDirectory | `internal static void DeleteDirectory(string path)` | 76 |  |
+| method | TryDeleteDirectory | `internal static void TryDeleteDirectory(string path)` | 82 |  |
+| method | TryDeleteEmptyDirectory | `internal static void TryDeleteEmptyDirectory(string path)` | 94 |  |
+| method | TryDeleteFile | `internal static void TryDeleteFile(string path)` | 107 |  |
+
+### GeneratedCodeDumpFinisher
+
+```csharp
+internal static class GeneratedCodeDumpFinisher
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpFinisher.cs:17` (md5: `c2eb8995bcc71df12da76d650c3e9850`, lines: 103)
+
+Background thread that runs `GeneratedCodeDumper.Tick` every 250 ms while there are jobs: it starts queued replays and moves the output of finished ones into the dump. Unlike `EditorApplication.update`, it keeps going while the Editor sits in the background. Not used in batch mode, which finishes the jobs on the calling thread.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| property | IsStopping | `internal static bool IsStopping { get; }` | 29 |  |
+| method | Start | `internal static void Start()` | 34 | Starts the thread unless it runs already. Call it after adding jobs. |
+| method | Stop | `internal static void Stop()` | 46 |  |
+
+### GeneratedCodeDumpIdentity
+
+```csharp
+internal static class GeneratedCodeDumpIdentity
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpIdentity.cs:7` (md5: `9b603ed77d27e1f4b3998df4eef50ea8`, lines: 40)
+
+Every name by which the generated-code dump shows itself: its Library/ folder, log prefix, thread, temp folder, menu and Preferences page.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | PackageName | `internal const string PackageName` | 14 | The package name. A constant because `PackageInfo.FindForAssembly` returns null when the package sits under Assets/. Up to 1.0.0 it was also the folder name under Library/ (`GeneratedCodeDumpPaths.LegacyRoot`). |
+| field | LibraryFolderName | `internal const string LibraryFolderName` | 20 | The folder under Library/ that holds the dump and its `.work/` folder, kept short for Windows' 260-character path limit. |
+| field | DisplayName | `internal const string DisplayName` | 22 |  |
+| field | LogPrefix | `internal const string LogPrefix` | 23 |  |
+| field | ThreadName | `internal const string ThreadName` | 24 |  |
+| field | ScratchFolderName | `internal const string ScratchFolderName` | 30 | Folder under the system temp folder that holds the compiler outputs, kept short for Windows' 260-character path limit. |
+| field | LegacyScratchFolderName | `internal const string LegacyScratchFolderName` | 35 | The temp folder's name up to 1.0.0. The migration deletes this project's folder in it. |
+| field | MenuRoot | `internal const string MenuRoot` | 37 |  |
+| field | SettingsPath | `internal const string SettingsPath` | 38 |  |
+
+### GeneratedCodeDumpJob
+
+```csharp
+internal sealed class GeneratedCodeDumpJob
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpJobs.cs:21` (md5: `05f06b1260978b7f2cf27e99751f9e2c`, lines: 242)
+
+One requested replay of an assembly whose output is not in the dump folder yet.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Id | `internal long Id` | 23 |  |
+| field | Assembly | `internal string Assembly` | 24 |  |
+| field | State | `internal GeneratedCodeDumpJobState State` | 25 |  |
+| field | ProcessId | `internal int ProcessId` | 26 |  |
+| field | ProcessStartUtcTicks | `internal long ProcessStartUtcTicks` | 27 |  |
+| field | StartedUtcTicks | `internal long StartedUtcTicks` | 33 | UTC wall time when the compiler was started: the job's timeout counts from it, and it is the `Dumped:` time of the files. |
+| field | Rerun | `internal bool Rerun` | 38 | A dump of the assembly was asked while its compiler ran: replay again once it is done. |
+
+### GeneratedCodeDumpJobList
+
+```csharp
+internal sealed class GeneratedCodeDumpJobList
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpJobs.cs:44` (md5: `05f06b1260978b7f2cf27e99751f9e2c`, lines: 242)
+
+The content of the job store: the jobs, at most one per assembly, and the next id to hand out.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Jobs | `internal readonly List<GeneratedCodeDumpJob> Jobs` | 46 |  |
+| field | NextId | `internal long NextId` | 47 |  |
+| method | Find | `internal GeneratedCodeDumpJob Find(string assembly)` | 49 |  |
+| method | FindById | `internal GeneratedCodeDumpJob FindById(long id)` | 54 |  |
+| method | Add | `internal GeneratedCodeDumpJob Add(string assembly)` | 62 | Adds a queued job for `assembly` with a fresh id. |
+| method | DropNotStarted | `internal bool DropNotStarted()` | 73 | Drops every replay that has not started: the queued jobs, and the reruns asked of running ones. Returns whether anything changed. |
+
+### GeneratedCodeDumpJobs
+
+```csharp
+internal static class GeneratedCodeDumpJobs
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpJobs.cs:97` (md5: `05f06b1260978b7f2cf27e99751f9e2c`, lines: 242)
+
+The dump jobs, stored in `GeneratedCodeDumpPaths.JobsFile` so they outlive the domain reload that follows every compile, and an Editor restart. Ids only ever go up, so a new job never reuses the scratch folder of an old one.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Read | `internal static GeneratedCodeDumpJobList Read(string path)` | 111 | The jobs in `path`; none when the file does not exist. Throws when it exists but cannot be read, so a caller never overwrites jobs it did not see. |
+| method | Write | `internal static void Write(string path, GeneratedCodeDumpJobList list)` | 120 |  |
+| method | Any | `internal static bool Any(string path)` | 126 |  |
+| method | Format | `internal static string Format(GeneratedCodeDumpJobList list)` | 131 |  |
+| method | Parse | `internal static GeneratedCodeDumpJobList Parse(string text)` | 157 | Parses `Format`'s output. A malformed line, or a second job with an id or assembly already seen, is skipped; `GeneratedCodeDumpJobList.NextId` always ends above the highest job id. |
+
+### GeneratedCodeDumpJobState
+
+```csharp
+internal enum GeneratedCodeDumpJobState
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpJobs.cs:12` (md5: `05f06b1260978b7f2cf27e99751f9e2c`, lines: 242)
+
+Where a dump job stands: waiting for a free compiler slot, or its compiler started.
+
+**Values:**
+
+| Name | Value | Line | Summary |
+|------|-------|------|---------|
+| Queued | — | 14 |  |
+| Running | — | 15 |  |
+
+### GeneratedCodeDumpLayout
+
+```csharp
+internal sealed class GeneratedCodeDumpLayout
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpOutput.cs:56` (md5: `0acc716509ba2c9af0a56aa2cd27cd8c`, lines: 449)
+
+Where one assembly's files go: its folder (full or cut), each file's path in it, and the files that get no path.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | AssemblyFolder | `internal string AssemblyFolder` | 58 |  |
+| field | OtherAssemblyFolder | `internal string OtherAssemblyFolder` | 63 | The assembly folder's other form (full or cut), which a sync removes; null when both are the same. |
+| field | Files | `internal readonly List<(GeneratedCodeDumpEntry Entry, string Path)> Files` | 68 | Every placed file with its '/'-separated path under `AssemblyFolder`, in entry order. |
+| field | TooLong | `internal readonly List<GeneratedCodeDumpEntry> TooLong` | 73 | Files whose path is over the budget even with every cut. |
+| field | Taken | `internal readonly List<GeneratedCodeDumpEntry> Taken` | 78 | Files whose path an earlier file took. |
+
+### GeneratedCodeDumpMigration
+
+```csharp
+internal static class GeneratedCodeDumpMigration
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpMigration.cs:18` (md5: `64ce798ead37103b51984d3cd99fb31d`, lines: 112)
+
+Moves a project off the 1.0.0 folders: `GeneratedCodeDumpPaths.LegacySettingsFile` becomes `GeneratedCodeDumpPaths.SettingsFile` as it is, unless that file already exists; then the rest of `GeneratedCodeDumpPaths.LegacyRoot` and this project's old temp folder are deleted.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | ShouldMoveSettings | `internal static bool ShouldMoveSettings(bool legacySettingsExists, bool settingsExists)` | 23 | Whether the legacy setting moves: only when it exists and the new file does not. |
+| method | Run | `internal static void Run()` | 31 | Migrates this project. Never throws. |
+| method | Migrate | `internal static List<string> Migrate(string legacyRoot, string legacySettingsFile, string settingsFile, string legacyScratchRoot, string legacyScratchBase)` | 68 | Moves `legacySettingsFile` to `settingsFile` when `ShouldMoveSettings` says so, then deletes `legacyRoot` and `legacyScratchRoot`, and `legacyScratchBase` when it is empty. Full paths. Returns what failed. |
+
+### GeneratedCodeDumpNames
+
+```csharp
+internal static class GeneratedCodeDumpNames
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpNames.cs:12` (md5: `668afc44c36e89fb05181aa2dff59e92`, lines: 104)
+
+Names in the dump: reserved Windows names made safe, and too-long names cut to `<start>~<fnv8 of the full name>`, so a cut name stays unique and readable.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | MaxUncutLength | `internal const int MaxUncutLength` | 17 | Names of this many characters or fewer are never cut. |
+| field | CutFolderStart | `internal const int CutFolderStart` | 22 | Characters a cut folder name keeps from the start of the full name. |
+| field | MinCutFileStart | `internal const int MinCutFileStart` | 27 | Fewest characters a cut file name keeps from the start of the full name. |
+| method | Tag | `internal static string Tag(string fullName)` | 45 | `~<fnv8>`: FNV-1a 32 of `fullName` as 8 lowercase hex digits. |
+| method | CutFolder | `internal static string CutFolder(string name)` | 54 | The folder name itself when it has at most `MaxUncutLength` characters, else its first `CutFolderStart` characters and `Tag`. |
+| method | CutFile | `internal static string CutFile(string fileName, int room)` | 67 | The file name itself when it fits in `room` characters, else `<start>~<fnv8><suffix>` exactly `room` long, keeping the `Suffix` whole. Null when fewer than `MinCutFileStart` characters of the start would remain. |
+| method | Suffix | `internal static string Suffix(string fileName)` | 84 | The part of a file name a cut keeps: `.generated.cs`, `.g.cs`, else the extension. |
+| method | SafeSegment | `internal static string SafeSegment(string segment)` | 97 |  |
+
+### GeneratedCodeDumpOutput
+
+```csharp
+internal static class GeneratedCodeDumpOutput
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpOutput.cs:107` (md5: `0acc716509ba2c9af0a56aa2cd27cd8c`, lines: 449)
+
+Turns the compiler's generated-files output (`<GeneratorAssembly>/<GeneratorType>/<hint name>`) into the dump layout `<Assembly>/<GeneratorAssembly>/<hint name>`, adds the header lines to every file and syncs it into the dump folder. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Entries | `internal static List<GeneratedCodeDumpEntry> Entries(IEnumerable<string> sources)` | 119 | One entry per generated file, from its paths relative to the generated-files output, in ordinal order. The hint becomes one file name in its generator assembly's folder. When an earlier file took that name there, the later one becomes `<stem>~<fnv8 of "<GeneratorType>/<hint>"><suffix>`. A file fewer than two folders deep keeps its path, every part made safe. |
+| method | Plan | `internal static GeneratedCodeDumpLayout Plan(IReadOnlyList<GeneratedCodeDumpEntry> entries, string dumpRoot, string assembly, GeneratedCodeDumpPathBudget budget)` | 160 | Places every entry under `<dumpRoot>/<assembly folder>/` within `budget`. If any file doesn't fit with full names, the assembly folder is cut for every file; then a generator folder is cut for all its files if any of them still doesn't fit; then each file that still doesn't fit gets its name cut to the room left, or is skipped as too long. Only counts lengths. |
+| method | Header | `internal static List<string> Header(string stamp, string assembly, string generatorAssembly, string generatorType, string hint)` | 209 | The header lines of a dumped file, with full names: `Dumped`, `Assembly`, `Generator: <assembly> / <type>` (left out when `generatorAssembly` is null) and `Hint`. |
+| method | Stamp | `internal static string Stamp(string text, IReadOnlyList<string> header)` | 224 | Adds `header` to the file's header: inside a `// <auto-generated>` block, after a `// <auto-generated/>` line, or else as new first lines. Keeps the file's line endings. |
+| method | Sync | `internal static GeneratedCodeDumpSyncResult Sync(string generatedFilesOut, string dumpRoot, string assembly, string stamp, GeneratedCodeDumpPathBudget budget)` | 257 | Writes every file under `generatedFilesOut` into `<dumpRoot>/<assembly folder>/` as `Plan` places it, with the header lines, then deletes every other file there and the assembly folder's other form. Files are replaced in place, so a file another process holds open keeps its older header. The assembly folder is created by the first write and removed when it ends up empty, so an assembly without generated files has no folder. Every listing, write and delete is tried on its own; never throws for a single file. |
+
+### GeneratedCodeDumpPathBudget
+
+```csharp
+internal readonly struct GeneratedCodeDumpPathBudget
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpPathBudget.cs:15` (md5: `65bce2e8265c8de09e69f527a4d1ff37`, lines: 67)
+
+How long a dump path may get on one OS: the whole file path, a folder path and one name. Windows counts UTF-16 characters (MAX_PATH 260 with the NUL, and 12 fewer for a folder); macOS and Linux count UTF-8 bytes (PATH_MAX 1024 on macOS, used for Linux too).
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Windows | `internal static readonly GeneratedCodeDumpPathBudget Windows` | 17 |  |
+| field | Unix | `internal static readonly GeneratedCodeDumpPathBudget Unix` | 18 |  |
+| property | Current | `internal static GeneratedCodeDumpPathBudget Current { get; }` | 20 |  |
+| property | File | `internal int File { get; }` | 26 | Longest full path of a file. |
+| property | Folder | `internal int Folder { get; }` | 31 | Longest full path of a folder. |
+| property | Name | `internal int Name { get; }` | 36 | Longest single file or folder name. |
+| property | Utf8Bytes | `internal bool Utf8Bytes { get; }` | 41 | True when lengths are counted in UTF-8 bytes, false for UTF-16 characters. |
+| constructor | GeneratedCodeDumpPathBudget | `internal GeneratedCodeDumpPathBudget(int file, int folder, int name, bool utf8Bytes)` | 43 |  |
+| method | Length | `internal int Length(string text)` | 51 |  |
+| method | Fits | `internal bool Fits(string folder, string fileName)` | 60 | True when `folder` (a full folder path) and `fileName` in it are both within the budget: the folder, the whole path with one separator, and the file name. |
+
+### GeneratedCodeDumpPaths
+
+```csharp
+internal static class GeneratedCodeDumpPaths
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpPaths.cs:15` (md5: `1127da1a4222128a164db4e3cf43ddad`, lines: 145)
+
+Every path used by the generated-code dump. Constants are relative to the project root.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | Root | `internal const string Root` | 21 | The dump: `<Root>/<Assembly>/<GeneratorAssembly>/<hint>`, next to `WorkFolder`. |
+| field | WorkFolder | `internal const string WorkFolder` | 23 |  |
+| field | JobsFile | `internal const string JobsFile` | 24 |  |
+| field | SessionMarkerFile | `internal const string SessionMarkerFile` | 25 |  |
+| field | SettingsFile | `internal const string SettingsFile` | 31 | The per-user switch. UserSettings/ is Unity's per-user folder: it survives deleting Library/, and Unity's standard .gitignore ignores it. |
+| field | LegacyRoot | `internal const string LegacyRoot` | 36 | The package's Library/ folder up to 1.0.0; `GeneratedCodeDumpMigration` removes it. |
+| field | LegacySettingsFile | `internal const string LegacySettingsFile` | 38 |  |
+| field | BeeArtifactsFolder | `internal const string BeeArtifactsFolder` | 39 |  |
+| field | ReplayFileName | `internal const string ReplayFileName` | 41 |  |
+| field | ErrorLogFileName | `internal const string ErrorLogFileName` | 42 |  |
+| property | ProjectRoot | `internal static string ProjectRoot { get; }` | 47 |  |
+| method | ToFullPath | `internal static string ToFullPath(string projectRelativePath)` | 50 |  |
+| method | WorkDirectory | `internal static string WorkDirectory(string assembly)` | 59 | Work folder of `assembly`, holding `ReplayFileName` and `ErrorLogFileName`. |
+| method | WorkDirectory | `internal static string WorkDirectory(string workFolder, string assembly, GeneratedCodeDumpPathBudget budget)` | 69 | `<workFolder>/<assembly>` (made safe) when both its files fit `budget`, else `<workFolder>/` and the assembly name cut like a dump folder. Only counts lengths. |
+| property | ScratchBase | `internal static string ScratchBase { get; }` | 81 | `<temp>/GenDump/`, shared by every project on this machine. |
+| property | LegacyScratchBase | `internal static string LegacyScratchBase { get; }` | 86 | `<temp>/GCDump/`, the temp folder up to 1.0.0. |
+| property | ScratchRoot | `internal static string ScratchRoot { get; }` | 94 | Root of every dump job's compiler output of this project, in the system temp folder: `<temp>/GenDump/<project hash>/`. The compiler nests each generated file two generator folders deep and those names can't be cut, so this stays short and independent of where the project lives, for Windows' 260-character path limit. |
+| property | LegacyScratchRoot | `internal static string LegacyScratchRoot { get; }` | 99 | This project's folder in `LegacyScratchBase`. |
+| method | ScratchDirectory | `internal static string ScratchDirectory(long jobId)` | 105 | Folder of dump job `jobId`: `GeneratedFilesDirectory` and `ReplayOutputDirectory`. |
+| method | GeneratedFilesDirectory | `internal static string GeneratedFilesDirectory(long jobId)` | 113 | The compiler's `-generatedfilesout` of dump job `jobId`: nothing but generated files. |
+| method | ReplayOutputDirectory | `internal static string ReplayOutputDirectory(long jobId)` | 122 | The assemblies the replay of dump job `jobId` compiles, as `<Assembly>.dll` and `<Assembly>.ref.dll`. |
+| method | Fnv1a | `internal static uint Fnv1a(string text)` | 131 | 32-bit FNV-1a over the UTF-8 bytes of `text`: the same on every machine and Unity version, unlike a runtime string hash. |
+
+### GeneratedCodeDumpProcess
+
+```csharp
+internal static class GeneratedCodeDumpProcess
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpProcess.cs:10` (md5: `e703972ca7d43e776b1e85659ad80a91`, lines: 119)
+
+Identifies processes by id and start time, so a process id the system reuses for another program is never taken for a dump compiler or for this Editor. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| property | CurrentId | `internal static int CurrentId { get; }` | 20 | This Editor's process id. |
+| property | CurrentStartUtcTicks | `internal static long CurrentStartUtcTicks { get; }` | 32 | This Editor's start time in UTC ticks, or 0 when the system does not tell. |
+| method | SameStart | `internal static bool SameStart(long startUtcTicks, long otherStartUtcTicks)` | 44 | True when two recorded start times belong to the same process; an unknown (0) time matches any. |
+| method | StartUtcTicks | `internal static long StartUtcTicks(Process process)` | 51 |  |
+| method | IsRunning | `internal static bool IsRunning(int processId, long startUtcTicks)` | 67 | True while process `processId` runs and is the one started at `startUtcTicks`. |
+| method | TryKill | `internal static void TryKill(int processId, long startUtcTicks)` | 91 | Stops process `processId` if it still runs and is the one started at `startUtcTicks`. Never throws. |
+
+### GeneratedCodeDumpRsp
+
+```csharp
+internal static class GeneratedCodeDumpRsp
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpRsp.cs:12` (md5: `6ec62c5db4822f0ab3cfc88c29224ccd`, lines: 107)
+
+Locates Unity's compiler response files: `Library/Bee/artifacts/<hash>.dag/<Assembly>.rsp`. Stale build graphs can sit beside the current one, so the newest file wins. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Find | `internal static string Find(string beeArtifactsDir, string assembly)` | 21 | The newest `*.dag/<assembly>.rsp`, or null when there is none. |
+| method | ListAssemblies | `internal static List<string> ListAssemblies(string beeArtifactsDir)` | 53 | Names of every assembly with a response file in the newest build graph (the one holding the newest response file), sorted. |
+| method | ReadArguments | `internal static List<string> ReadArguments(string rspPath)` | 89 | The arguments of `rspPath`, one per line, followed by those of its companion `<Assembly>.rsp2` (per-package `/pathmap`) when there is one: Unity passes both to the compiler, in that order. |
+
+### GeneratedCodeDumpSession
+
+```csharp
+internal static class GeneratedCodeDumpSession
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpSession.cs:11` (md5: `f040e4a51c465586cfdafba46f95f100`, lines: 65)
+
+The session marker, `GeneratedCodeDumpPaths.SessionMarkerFile`: the process id and start time of the Editor that last found the dump on. It tells a domain reload, which keeps the process, from an Editor start or the setting being switched on, which both call for a full dump. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | ShouldDumpAll | `internal static bool ShouldDumpAll(bool enabled, bool markerIsThisProcess, bool rootExists)` | 17 | Dump every assembly when the dump is on and either this Editor process has not seen it on yet, or the dump folder, `GeneratedCodeDumpPaths.Root`, is missing. |
+| method | FormatMarker | `internal static string FormatMarker(int processId, long processStartUtcTicks)` | 22 |  |
+| method | TryParseMarker | `internal static bool TryParseMarker(string text, out int processId, out long processStartUtcTicks)` | 31 | Reads `<process id> [<start ticks>]`; a missing start time reads as 0 (unknown). |
+| method | IsMarkerOf | `internal static bool IsMarkerOf(string markerText, int processId, long processStartUtcTicks)` | 58 | True when `markerText` names the process `processId` started at `processStartUtcTicks`. |
+
+### GeneratedCodeDumpSettings
+
+```csharp
+internal sealed class GeneratedCodeDumpSettings
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpSettings.cs:19` (md5: `9e362b011ba68e1176e7bf9e64310fab`, lines: 111)
+
+Whether the generated-code dump runs for this user in this project, stored as `{"enabled": true}` in `GeneratedCodeDumpPaths.SettingsFile`. Under UserSettings/, Unity's per-user folder, so it survives deleting Library/, Unity's standard .gitignore keeps it out of version control, and each developer turns it on for themselves. Batch mode on the same machine follows it too.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| constructor | GeneratedCodeDumpSettings | `internal GeneratedCodeDumpSettings(string path)` | 29 |  |
+| property | Current | `internal static GeneratedCodeDumpSettings Current { get; }` | 37 | The settings of this project, re-created after each domain reload. |
+| property | IsEnabled | `internal static bool IsEnabled { get; }` | 40 |  |
+| property | Enabled | `internal bool Enabled { get; set; }` | 46 | Re-reads the file when its write time or length changed since the last read. Setting it saves the file atomically, creating its folder. |
+
+### GeneratedCodeDumpSettingsFile
+
+```csharp
+internal static class GeneratedCodeDumpSettingsFile
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpSettingsFile.cs:14` (md5: `a8960ce56a06cea8c4b438abd0a29d92`, lines: 231)
+
+The text of the settings file, `{"enabled": true}`: written and parsed without `JsonUtility`, so the settings watcher can read it off the main thread. No UnityEditor use.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | EnabledKey | `internal const string EnabledKey` | 16 |  |
+| method | Format | `internal static string Format(bool enabled)` | 18 |  |
+| method | TryParse | `internal static bool TryParse(string json, out bool enabled)` | 26 | False when `json` is not a flat JSON object with a boolean `enabled` (or none). |
+
+### GeneratedCodeDumpSettingsProvider
+
+```csharp
+internal sealed class GeneratedCodeDumpSettingsProvider : SettingsProvider
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpSettingsProvider.cs:10` (md5: `ddd410b00c6fb446e055514f5869d16d`, lines: 93)  
+**Base:** `SettingsProvider`
+
+Preferences page `Preferences/Generated Code Dump`: this user's switch for the generated-code dump, and its output folder.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | OnGUI | `public override void OnGUI(string searchContext)` | 33 |  |
+
+### GeneratedCodeDumpSettingsWatcher
+
+```csharp
+internal static class GeneratedCodeDumpSettingsWatcher
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpSettingsWatcher.cs:18` (md5: `02a76cee156eec476996bd082d703c80`, lines: 199)
+
+Calls back, off the main thread, about 300 ms after the settings file is created, changed, renamed or deleted, so an edit made outside the Editor applies even while the Editor sits in the background. Not used in batch mode.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Start | `internal static void Start(Action onChange)` | 34 |  |
+| method | Stop | `internal static void Stop()` | 48 |  |
+| method | Target | `internal static (string Folder, string Filter) Target(string settingsFile, bool settingsFolderExists)` | 66 | The folder to watch and the name to watch in it for `settingsFile` (a full path): its folder for the file itself, or, while that folder is missing, the folder above for that folder's name. |
+
+### GeneratedCodeDumpSyncResult
+
+```csharp
+internal sealed class GeneratedCodeDumpSyncResult
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeDumpOutput.cs:84` (md5: `0acc716509ba2c9af0a56aa2cd27cd8c`, lines: 449)
+
+What a sync could not do, one line per file with its path under the dump root.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| field | TooLong | `internal readonly List<string> TooLong` | 89 | Files skipped, or not written or deleted, because their path is over the OS limit. |
+| field | Failed | `internal readonly List<string> Failed` | 94 | Files that could not be written or deleted, with the reason. |
+
+### GeneratedCodeMenuItems
+
+```csharp
+internal static class GeneratedCodeMenuItems
+```
+
+**Source:** `Assets/Package/GeneratedCodeDump/Editor/GeneratedCodeMenuItems.cs:9` (md5: `0b42131fab839b8fda708545e3416535`, lines: 46)
+
+Menu items of the generated-code dump, under Tools/Generated Code Dump/.
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | ToggleEnabled | `internal static void ToggleEnabled()` | 14 |  |
+| method | DumpNow | `internal static void DumpNow()` | 27 |  |
+| method | OpenFolder | `internal static void OpenFolder()` | 33 |  |
+| method | OpenSettings | `internal static void OpenSettings()` | 41 |  |
+
+<!--
+Used only when api.md is single-file (Step 4 default branch). When chunking
+is active (Step 4 chunked branch), api.md becomes a Contents-table index
+rendered from api-index.md.template, and per-namespace bodies are emitted
+to Documentation~/api/<Namespace>.md from api-chunk.md.template.
+Line 2 is the render stamp (SKILL.md "Output contract"); Step 3.6 re-renders
+this file whenever the scanner or API_RENDER_VERSION differs.
+
+Each namespace section follows this exact shape:
+
+## `{namespace}`
+
+### {fullDisplayName}
+
+```csharp
+{declaration — the full header from the manifest, verbatim, possibly multi-line}
+```
+
+**Source:** `{file}:{line}` (md5: `{md5}`, lines: {lines})
+**Partial across:** {partialAcross} (omit line unless the type is partial across files)
+**Attributes:** `[Attr1]`, `[Attr2]` (omit line if none)
+**Base:** `{base1}`, `{base2}` (omit if empty)
+
+{summary}
+
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Foo | `public void Foo()` | 88 | … |
+
+Enums get a `**Values:**` table (| Name | Value | Line | Summary |) instead
+of Members; delegates get no table (the csharp block is their signature).
+
+The exact shape of the Source parenthetical — `(md5: \`<32-hex>\`, lines: <n>)` —
+is the contract the Step 3.6 fast-update check greps for, on the Source line
+and on every Partial across entry. Do not reflow it (e.g. drop the backticks
+around the hex, swap the order, or put it on a new line) — the check will
+silently stop skipping unchanged namespaces.
+
+{partialAcross} lists every non-primary declaration of a partial type in the
+Source shape, comma-separated, ordered by path. For such a type the Members
+position column is `File:Line` (cells like `Context.Entity.cs:55`) and rows
+from every declaration are merged; otherwise members share the type's file and
+the **Line** column gives the line within it. Anchors are the Markdown
+auto-slug of the heading (`### Context<TEntity>` → `contexttentity`) regardless
+of the file/line annotation.
+
+Render every type whose effectiveVisibility is public / protected / internal;
+skip private types and types nested in private types. Never omit a rendered
+type: one with no non-private members and no summary gets its heading,
+declaration, Source, Base and "No public members." plus a renderer warning.
+Omit namespaces with no renderable types.
+-->