Feat: Per-file incremental generator output

[DJGosnell]

Summary

• Closes Feat: Per-File Incremental Generator Output #3
• Restructures both Phase 1 (entity/context) and Phase 2 (interceptors) of QuarryGenerator so that a change in a single source file only regenerates the output files relevant to that file
• Groups interceptors by execution chain instead of by invocation kind for more readable output
• Output filenames use human-readable sanitized source paths instead of opaque hex hashes for easy identification

Reason for Change

Currently, .Collect() on all usage sites funnels into a single Execute() call that regenerates everything. Any change to any source file triggers full regeneration of all interceptor files — O(n) work for O(1) changes.

Impact

Phase 0 — Model value equality: All 25+ pipeline model types now implement IEquatable<T> with structural comparison. Added EquatableArray<T>, EquatableDictionary<TKey,TValue>, and EqualityHelpers for collection equality. Roslyn types (SyntaxNode, Location) are excluded from equality since they use reference identity.

Phase 1 — Per-context entity generation: Entity/context/metadata generation is registered directly on contextDeclarations (per-value, no Collect()). Each context is independently cached — changing one context no longer regenerates files for other contexts. Cross-context diagnostics (duplicate TypeMapping) use a separate collected pipeline.

Phase 2 — Per-file interceptor output: The interceptor pipeline uses SelectMany(GroupByFileAndProcess) to fan collected data into per-file FileInterceptorGroup objects, each independently cached by Roslyn. Output filenames use a sanitized source path tag: {Context}.Interceptors.{src_Models_User}.g.cs. Diagnostics are carried through the pipeline as DiagnosticInfo objects and reported in the output callback.

Chain-based grouping: Interceptors are now grouped by execution chain (#region Chain: ExecuteFetchAllAsync at line 42) instead of by InterceptorKind (#region Where Interceptors), so related clause and execution sites appear together.

Human-readable file tags: Replaced SHA256-based hex hashes with sanitized path tags (e.g. src_Models_User instead of a1b2c3d4). This makes it trivial to find the generated interceptor file for any given source file. The FileHasher utility strips extensions, drive letters, and leading slashes, then replaces path separators with underscores.

Migration Steps

• Output filenames change from {Context}.Interceptors.g.cs to {Context}.Interceptors.{file_tag}.g.cs — this is transparent to consumers since interceptor files use file scoped classes
• No API changes — all changes are internal to the generator

Performance Considerations

• GroupByFileAndProcess still runs on every change (enrichment + chain analysis), but this is relatively cheap
• The expensive string-building in InterceptorCodeGenerator only runs for files whose FileInterceptorGroup equality check fails
• Projects with many source files using Quarry will see proportionally fewer regenerations

Security Considerations

• No security impact — changes are internal to the compile-time source generator

Breaking Changes

• Consumer-facing: None — interceptor files are file scoped and invisible to consumers
• Internal: Test assertions updated for new output filename patterns and chain-based region names

🤖 Generated with Claude Code

[DJGosnell]

Code Review: Per-File Incremental Generator Output

Overview

Restructures QuarryGenerator so a change in one source file only regenerates interceptor output for that file. Adds value equality to 25+ model types, splits entity generation into per-context output, and implements a SelectMany-based per-file pipeline with chain-based interceptor grouping.

Correctness

1. FileInterceptorGroup.fileSites filter readability — The filter s.IsAnalyzable || !fileChainMemberIds.Contains(s.UniqueId) is a double-negative that's hard to parse. Since non-analyzable non-chain-members were already filtered out in allSitesForGeneration, s.IsAnalyzable alone would be equivalent and clearer.

2. Orphaned diagnostic location fallback — When no SyntaxTree is available for orphaned diagnostics, Location.None is used. This is acceptable since it only happens for files with exclusively non-analyzable sites (rare), but worth documenting.

3. EquatableArray<T> and EquatableDictionary<TKey,TValue> are created but unused — These types were created in Phase 0 but no model type uses them — all models use IReadOnlyList<T> with manual EqualityHelpers calls. Consider removing or adding a comment explaining they're infrastructure for future use.

Performance

4. O(n×m) chain-to-site matching in InterceptorCodeGenerator — The chain grouping uses allSitesForGeneration.FirstOrDefault(s => s.UniqueId == clause.Site.UniqueId) inside nested loops. For large files this is O(chains × clauses × sites). Build a dictionary lookup instead:

   var siteByUniqueId = allSitesForGeneration.ToDictionary(s => s.UniqueId);

5. EquatableArray.GetHashCode hashes all elements — For large arrays this runs on every equality check. Consider caching the hash or limiting to first N elements.

Style

6. Diagnostic IDs as magic strings — "QRY001", "QRY014", etc. are duplicated between DiagnosticInfo construction sites and GetDescriptorById. Consider using the descriptors' .Id property or defining constants.

Test Coverage

7. Tests updated appropriately — All 8 test files updated for the new stableFileHash parameter and region naming.

8. Missing tests — No dedicated tests for:

   • EquatableArray<T> / EquatableDictionary<K,V> equality semantics
   • FileHasher.ComputeStableHash determinism
   • EqualityHelpers edge cases
   • Incremental caching behavior (verifying cache hits/misses via GeneratorDriver tracked steps)

Recommendations

Priority	Item
P1	Fix O(n×m) lookup in chain grouping (#4)
P2	Add unit tests for EqualityHelpers, FileHasher, and key model equality (#8)
P3	Remove unused EquatableArray/EquatableDictionary or document as future infra (#3)
P3	Replace magic diagnostic ID strings with descriptor references (#6)

Verdict

The architecture is sound — SelectMany fan-out is the standard Roslyn pattern for per-file incremental output. Equality implementations are thorough and correctly exclude Roslyn reference-equality types. Chain-based grouping is a nice readability improvement. Main concerns are missing test coverage for infrastructure types and the O(n×m) lookup.