Reviewer reading guide: upstream code to study for the Strawberry Shake fork PRs

[cliedeman]

Reading guide for reviewing the fork's Strawberry Shake pull requests. Each cluster of PRs maps to the upstream (ChilliCream/graphql-platform) source you should read to understand the change. Source links point to upstream main; the three fork-only files (FORK.md, ci-fork.yml, release-fork.yml) have no upstream equivalent and live on the stackworx-dotnet fork.

The Strawberry Shake generator is a 3-stage pipeline: analyze (GraphQL → model) → map (model → descriptors) → generate (descriptors → C#). Read the Foundation once, then the group(s) you care about.

Foundation — the codegen pipeline (read first)

• DocumentAnalyzer.cs + .CollectOutputTypes / .CollectInputObjectTypes / .CollectEnumTypes — entry: how parsed docs become a ClientModel.
• Models: ClientModel.cs, OperationModel.cs, OutputTypeModel.cs, OutputFieldModel.cs, EntityModel.cs — the in-memory model everything downstream consumes.
• MapperContext.cs + TypeDescriptorMapper.cs — model → descriptors.
• CSharpGenerator.cs + CSharpGeneratorSettings.cs — orchestration + knobs.
• Test harness: GeneratorTestHelper.cs + CSharpCompiler.cs — how every codegen PR is tested (snapshot + Roslyn compile).

Group 1 — fragments / interfaces / unions

Understand PRs #9, #7, #8, #10, #15. These hinge on how selections and fragments become output-type models.

• FieldCollector.cs, FieldSelection.cs, SelectionSet.cs, SelectionSetInfo.cs, ISelectionSetVariants.cs — selection-set structures + the dedupe/lookup key (the crux of fix(strawberryshake): resolve output type for composite field selected directly and via fragment #9).
• FragmentHelper.cs, Fragment.cs, FragmentNode.cs, FragmentKind.cs — inline + named fragments → interfaces (fix(strawberryshake): dedupe duplicate fragment spreads in interface list (CS0528) #7 = implements list; fix(strawberry-shake): populate union member classes for fragment selections #8 = CollectFields descending into abstract named fragments).
• SelectionSetAnalyzer.cs, InterfaceTypeSelectionSetAnalyzer.cs — object vs interface/union selection sets → output types.
• The fix(strawberryshake): resolve output type for composite field selected directly and via fragment #9 throw site: TypeDescriptorMapper.cs GetFieldTypeDescriptor + OperationModel.cs TryGetFieldResultType.

Group 2 — runtime result-builder & entity store

Understand PRs #11, #12. Both edit the generator that emits the runtime deserialization/entity-update code.

• Generator: JsonResultBuilderGenerator.cs + _UpdateEntity / _EntityOrDataType / _DeserializeDataType / _BuildData / _ArrayHandler
• Runtime (what the generated code calls): EntityStore.cs, EntityStoreUpdateSession.cs, EntityStoreSnapshot.cs, EntityId.cs, EntityIdOrData.cs, OperationResultBuilder.cs, IOperationResultDataFactory.cs — explains why default!-overwrite loses data (fix(strawberryshake): preserve entity fields across differing selection sets (#8063) #11) and why throwing on unknown __typename breaks (fix(strawberryshake): degrade gracefully on unknown abstract type at runtime #12).
• Mappers: ResultBuilderDescriptorMapper.cs, EntityTypeDescriptorMapper.cs, ResultFromEntityMapper.cs · MethodCallBuilder.cs

Group 3 — operation/service generation & uploads

Understand PR #14.

• OperationServiceGenerator.cs, OperationServiceInterfaceGenerator.cs, MethodCallBuilder.cs — emits the typed client methods + file-upload mappers (the u variable + duplicate MapFilesFromType).
• OperationDescriptorMapper.cs, TypeDescriptorMapper.InputTypes.cs

Group 4 — codegen performance

Understand PRs #18, #19, #20 (verify behavior is identical — no snapshot changes expected).

• TypeDescriptorMapper.cs + TypeDescriptorMapper.InputTypes.cs (perf(strawberry-shake): index type descriptor lookups to remove O(N²) mapping #20), DataTypeDescriptorMapper.cs (perf(strawberryshake): index data-type components by runtime name #18), CSharpGenerator.cs (perf(strawberry-shake): format single-file output per namespace #19).

Group 5 — Razor/Blazor: persisted state, interface type, bUnit

Understand PRs #2, #3, #5. Read FORK.md "Tracked work items 1 & 2" first — the intent spec.

• Fork intent: FORK.md
• Razor runtime: UseQuery.cs, UseSubscription.cs, UseFragment.cs, DataComponent.cs
• Result types: IOperationResult.cs, OperationResult.cs, IOperationResultBuilder.cs
• Generation hooks: DependencyInjectionGenerator.cs, RazorQueryGenerator.cs, RazorSubscriptionGenerator.cs; settings CSharpSyntaxGeneratorSettings.cs, TypeNames.cs, StrawberryShakeSettings.cs

Group 6 — transport: SSE subscription streaming

Understand PR #16.

• HttpConnection.cs, IHttpConnection.cs — the HTTP/SSE read loop (Blazor WASM streaming fix).
• IConnection.cs, OperationExecutor.cs, OperationExecutor.Observable.cs, IResultPatcher.cs

Group 7 — fork CI & publishing

Understand PRs #4, #5.

• Upstream: ci.yml (the heavy matrix), Directory.Packages.props
• Fork-only: ci-fork.yml, release-fork.yml, FORK.md

Group 8 — validation fuzzing

Understand PR #6 (review = the findings + method, not a code change).

• Validation/ and the rules the findings implicate: ValueVisitor.cs, VariableVisitor.cs, ArgumentVisitor.cs, FieldSelectionsRule.cs

---

Suggested path: Foundation first, then Group 1 and Group 2 (they unlock #7/#8/#9/#10/#11/#12/#15 and make the perf and Razor groups easy). Groups 6–8 are independent and can be read standalone.

All source links target the upstream repo ChilliCream/graphql-platform on main; the fork-only files (FORK.md, ci-fork.yml, release-fork.yml) have no upstream equivalent and link to the stackworx-dotnet fork. Upstream main moves forward, so if a file is later renamed upstream a link may drift; ping to pin them to the fork's base commit (6e5b640166) instead.

— Claude
🤖 Generated with Claude Code