🔧 Fix a Source Generator Never Firing on an Incremental Build
An incremental source generator builds a pipeline of value providers, and the whole point of the incremental model is that a stage only re-runs when its inputs actually change, judged by equality comparison on the values flowing through it. A pipeline stage that produces a custom record as its output without that type having correct, value-based equality — for example, one holding an array without overriding equality to compare elements, since arrays compare by reference by default — will either appear to have “changed” on every single build when nothing relevant did, or the more confusing opposite: appear unchanged across builds that compare equal by reference but shouldn’t, silently leaving stale generated code in place on an otherwise successful incremental build.
🔎 The Problem
// Wrong: holds an array; two instances with identical contents are NOT
// equal, so the incremental cache thinks every build's output "changed."
readonly record struct ModelInfo(string Name, string[] Properties);
// Fix: implement value-based equality explicitly instead of relying on
// the record's compiler-generated default.
readonly record struct ModelInfo(string Name, ImmutableArray<string> Properties)
{
public bool Equals(ModelInfo other) =>
Name == other.Name && Properties.SequenceEqual(other.Properties);
public override int GetHashCode() =>
HashCode.Combine(Name, Properties.Length);
}
✅ Fix: Give Your Pipeline Types Real Equality
- Audit every custom type that flows through an incremental pipeline stage for value-based equality — a plain record with an array or list member looks like it has value equality but doesn’t, because the compiler-generated `Equals` compares those members by reference.
- Prefer `ImmutableArray<T>` with an explicit `SequenceEqual`-based equality override — since even `ImmutableArray<T>`’s own default equality is reference-based — over a plain array or list for anything carried through the pipeline.
- Add a test that runs the generator twice against two separate but logically identical compilations and asserts the same cached pipeline output is reused — this is the one test that catches a broken-equality regression, since a single-build functional test can’t distinguish “ran once and worked” from “will correctly skip re-running when nothing changed.”
🚨 Why This Is Dangerous
- A source generator with broken incremental equality doesn’t fail a build and doesn’t produce wrong code on a full rebuild — it specifically produces stale generated code on an incremental build after a real source change, so the bug reproduces inconsistently depending on exactly how someone built the project.
An incremental pipeline only skips work it can prove is unnecessary – and a broken Equals is exactly what convinces it something unnecessary is.
