Repository navigation
Extract a reusable generator diagnostics helper #185
Copy link
Copy link
Closed
Labels
enhancementNew feature or requestNew feature or request
Description
Problem
Every generator in this repo hand-rolls the same diagnostic plumbing. QuantitiesGenerator declares four DiagnosticDescriptor fields (SEM001–SEM004) and LogarithmicScalesGenerator a fifth (SEM005), each with its own private Report helper:
private static readonly DiagnosticDescriptor InvalidScaleDefinition = new(
id: "SEM005",
title: "logarithmic.json scale definition is invalid",
messageFormat: "logarithmic.json validation issue: {0}",
category: Emit.DiagnosticCategory,
defaultSeverity: DiagnosticSeverity.Warning,
isEnabledByDefault: true);
private static void Report(SourceProductionContext context, string message) =>
context.ReportDiagnostic(Diagnostic.Create(InvalidScaleDefinition, Location.None, message));Nothing about that shape is Semantics-specific. Three problems come with it:
- The boilerplate is copied per generator, and the IDs are allocated by hand — the next generator author has to grep for the highest
SEM0xxin use. GeneratorBasedoes not follow the scheme. It reports JSON parse failures asCONV001in category"SourceGenerator"— a leftover from when it served onlyConversionsGenerator, and inconsistent with everything derived from it.AnalyzerReleases.Shipped.md/AnalyzerReleases.Unshipped.mdare maintained by hand. WithEnforceExtendedAnalyzerRules=true, RS2008 fires when a descriptor is not tracked there, so this is a real recurring cost and an easy thing to forget.
Proposal
Extract into the shared toolkit:
- A
DiagnosticFactory/ descriptor-registry type parameterized by prefix (SEM,CONV, whatever the consumer uses) and category, so a generator declares descriptors declaratively and reporting is one call. - Convenience overloads for the recurring shapes: "metadata validation issue", "unknown reference in metadata", "referenced file not found" — the three that account for all five descriptors here.
- Optional
Locationsupport. Everything here reportsLocation.None, so a typo indimensions.jsongives no file or line. Since the metadata arrives as anAdditionalTextthe generator can map an offset to aLocation, which would make these diagnostics genuinely navigable. Worth doing as part of the extraction rather than after. - A check (test or build step) that every declared descriptor is present in
AnalyzerReleases.*.md, so RS2008 is caught before it fires.
Acceptance criteria
- All SEM00x descriptors are declared through the shared helper; no generator declares a raw
DiagnosticDescriptor. -
GeneratorBase's JSON-failure diagnostic uses the consumer-configured prefix and category —CONV001/"SourceGenerator"is gone. - Existing diagnostic IDs and message formats are unchanged (they are documented in
CLAUDE.mdanddocs/physics-generator.md). - Analyzer-release tracking is verified automatically.
Context
Part of #181. Closely related to #182 — the base generator's diagnostics are the worst offender.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
enhancementNew feature or requestNew feature or request
Activity
refactor: shape the generator infrastructure for extraction [minor]