Gengora.CSharp.Formatting 2.5.0

Gengora.CSharp.Formatting

Apply Gengora's compiled C# formatting rules to Roslyn documents, including generated code before it is written to the consumer project. The same profile is used by the formatter CLI and semantic MCP.

Install from a feed containing this version:

dotnet add package Gengora.CSharp.Formatting

solution = await CSharpFormatter.FormatAsync(
    solution, generatedDocumentIDs, cancellationToken);

Use Gengora.CSharp.Formatting and pass document IDs from the target solution after generation. The formatter needs the target project's semantic model; it preserves that project's references and synchronizes linked documents. It does not load or restore projects. AnalyzeAsync reports style findings that require changes in the generator's template rather than automatic layout.

Compiler integrations can call the same rules directly on a semantic model:

var findings = CSharpFormatter.Analyze(semanticModel, cancellationToken);

This API is available for both .NET 11 and .NET Standard 2.0. The latter contains the shared compiler rules without Workspaces, MSBuild, Gengora hosting or receipt storage. Supply the semantic model from the completed compilation so references between generated sources are resolved. Document formatting remains a .NET 11 API.

Source generators can format a complete syntax root before adding it to the compilation, including when generated peer declarations are not yet available:

var formatted = CSharpFormatter.FormatSyntax(root, cancellationToken);

This entry point is also available on .NET Standard 2.0. It reuses the document formatter's structural, layout, alignment and spacing rules without opening a workspace. Generated output uses four-space indentation and LF line endings. It does not rename symbols or infer types; run semantic validation against the completed compilation. Keep source digests bound to the formatted output.

Syntax, generated-source preparation and document formatting share one layout plan and renderer. Calls and method/constructor headers use the same width policy instead of argument-count thresholds. Assignment alignment runs once after layout. Automatic accessors stay inline; literal contents, comments, directives and disabled source text are retained. The renderer writes through a pooled character buffer rather than repeated whole-document string rewrites. The current implementation is a source checkpoint awaiting its consolidated build, formatting and regression batch; performance remains unmeasured.

To check generated files during a normal compiler build, install the separate Gengora.CSharp.Formatting.Analyzers package from a feed containing this version. It bundles the analyzer and the .NET Standard rule library. The analyzer uses Roslyn's generated-code classification and reports the existing GCSF001–GCSF016 findings only for generated code. It checks generated files containing declarations or top-level statements, including physical .g.cs files. Generated assembly metadata, import-only and empty files have no declarations to validate and are excluded. This follows the syntax, without a filename blacklist. Ordinary authored files are outside this analyzer's scope. Installing this opinionated analyzer opts into the same rules for generated declarations from other producers too.

Blocking findings are compiler errors. GCSF002 length findings remain informational, including when warnings are treated as errors. Short direct Boolean checks retain the formatter's existing allowance. This analyzer reports template defects; it does not rewrite source or replace the host's formatting step.

GCSF016 reports a constant equality comparison that can safely become is or is not. The semantic formatter rewrites enum members, literals and declared constants, including null and reversed operands. Custom operators, dynamic or unresolved inputs, NaN, reference comparisons with non-null constants and incompatible numeric conversions retain their operators. Expression-tree lambdas and query clauses remain valid; ordinary delegates and Enumerable queries can use patterns. Syntax-only formatting cannot make this binding decision. See the complete regression proof.

For a reviewed exception, surround the comparison with #pragma warning disable GCSF016 and #pragma warning restore GCSF016. The shared semantic rule checks Roslyn's effective diagnostic at the original operator, so the protected comparison retains ==/!=. Other style rules and comparisons outside that region remain active. The normal MacBook source build and all 41 focused cases pass; successor package qualification and consumer uptake remain open. See the candidate and proof boundary.

Generator packages can instead provide an analyzer restricted to their own output. Expose CSharpFormatter.GeneratedCodeDiagnostics as its supported diagnostics and forward owned generated-source callbacks to CSharpFormatter.AnalyzeGeneratedCode. This reuses the same rules, severity and source locations while leaving other generators' output alone. The GraphQL package uses this route; the separate all-generated-code package retains its explicit broader scope.

A Roslyn generator can implement IReferencedMetadataGenerator to read referenced projects through exact compiled metadata images. This marker is available on both target frameworks. Images preserve metadata and documentation, but expose no source syntax or method bodies; reuse verification compares the generated sources and diagnostics with the source-compilation route. Generators without this marker keep that source route.

Pipeline input scope is chosen separately at registration with RoslynGenerator<TGenerator>(name, projectPath, PipelineInputScope.ProjectClosure, createGenerator). The ordinary overload keeps PipelineInputScope.Solution; IProjectClosureSourceGenerator was replaced by this registration API.

Keep generated-output review and compilation after formatting. A passing formatter check does not prove generated behavior or replace an Origin/Result comparison. The formatter executable and MCP host remain separate tools.

See the C# tooling guide for build, test and package verification.