QueryMutationAnalyzer

Remarks

docs/plan/04-ecs-and-scripting.md § Structural change safety states this as something the tooling already does: "Direct structural mutation on the main thread outside iteration is allowed and fast; the analyzer flags it inside a query body." The two mechanisms that make it safe — CommandBuffer and its ParallelWriter — are both opt-in, so an author who has not reached for one is not told.

⚠ The failure is the worst shape there is: it is usually fine. Adding or removing a component moves the entity to another archetype and can split the chunk the loop is standing in. That corrupts the walk only when it moves the entity the loop is on or the chunk it is reading — so three entities in a test pass and three thousand in a level fail intermittently. Nothing throws.

What counts as a query body. Three forms, because the ECS offers three: the delegate passed to world.Query(…)/QueryWithEntity(…), a foreach over world.Chunks(…) or query.Chunks(…), and the Update of a struct visitor handed to ForEach. The visitor is the one that cannot be seen from the call site at all — its body is a different file.

Suppression is a #pragma and it is meant to be used. Mutating the entity a loop is about to leave is sometimes exactly right, and a rule with no way out becomes a rule people turn off wholesale. #pragma warning disable VXS0415 with a line saying why is the intended escape; a CommandBuffer played back at the sync point is the intended answer.

Fields and properties (2)

• public const string DiagnosticId

  The id reported for a structural change inside a query body.

• public override ImmutableArray<DiagnosticDescriptor> SupportedDiagnostics

  Returns a set of descriptors for the diagnostics that this analyzer is capable of producing.

Methods (1)

• public override void Initialize(AnalysisContext context)

  Called once at session start to register actions in the analysis context.

Used by (1)

• QueryMutationTestsVixen.Engine.Generators.Tests