FixPortal.CodeStyle 0.1.12

FixPortal.CodeStyle

Shared C# code-style and architecture-rule packages for FixPortal .NET repositories.

Shared C# code-style and analyzer configuration for FixPortal .NET repositories, delivered as NuGet packages so every repo enforces the same rules and a rule change rolls out with a version bump instead of N hand-edits.

New here? docs/EXPLAINER.md is the full plain-language walkthrough — the problem, the design, how enforcement works, the auth model, and how to release a rule change. To migrate an existing repo, use the canonical prompt in docs/adopt-prompt.md.

What it does

Adding the package to a project:

1. Registers a global AnalyzerConfig (FixPortal.CodeStyle.globalconfig) carrying every style/analyzer rule and severity — braces (IDE0011), no redundant parentheses (IDE0047), file-scoped namespaces (IDE0161), accessibility modifiers (IDE0040), expression-bodied members, pattern-matching preferences, naming rules, and the curated CA/IDE/Sonar suppression set.
2. Sets EnforceCodeStyleInBuild=true, so the IDExxxx style rules run at build time, not just in the IDE. Rules set to error fail the build directly; combined with TreatWarningsAsErrors, warning-level rules do too.
3. Bundles the house analyzer (SonarAnalyzer.CSharp, version-pinned) so consumers do not declare it themselves.

Deliberately not silenced (and never should be without a documented per-project reason): security (CA5394/CA5401/CA2326/CA2327/S6781), nullable-reference (CS8600/CS8602/CS8603/CS8604/CS8618), IDisposable safety (CA1063/CA1816/CA2213/S3881). CS8602 and CS8604 are warnings; the others retain their compiler defaults.

Unused-usings (IDE0005) is a separate case: it stays at suggestion, not warning, because at warning+ Roslyn also emits an EnableGenerateDocumentationFile build diagnostic on any project without <GenerateDocumentationFile>true</GenerateDocumentationFile>, which reds the build under TreatWarningsAsErrors even with zero unused usings. suggestion still surfaces the finding (squiggle + fix-on-save); a repo wanting build/CI enforcement opts in locally with GenerateDocumentationFile=true (+ NoWarn CS1591) and IDE0005.severity=warning.

Install

In the consuming repo's Directory.Build.props (so it applies to every project):

<ItemGroup>
  <PackageReference Include="FixPortal.CodeStyle" Version="<latest>" PrivateAssets="all" />
</ItemGroup>

The package is marked a development dependency, so PrivateAssets="all" is implied — include it anyway for clarity. It never flows to your package's downstream consumers.

Local .editorconfig

The global config carries only rules, not formatter layout (indent width, newline and spacing rules) — a global config has no per-file-type sections. Keep a thin local .editorconfig at the repo root for those keys; copy the template in assets/consumer.editorconfig. The template also contains the documented IDE0011 and IDE0049 compatibility entries required by dotnet format 10.0.204. Roslyn does not activate those fixers from a packaged global config alone, so the local entries repeat the package-owned preferences without changing their meaning. Do not copy other rules back into it — a local copy only re-drifts. Add a local rule override only for a genuine project-specific need, with a comment explaining why (e.g. re-enabling the culture rules CA1304/1307/1308/1309/1311 in a service that serves localized text). CSharpier owns C# whitespace, wrapping, and layout; the package disables the competing IDE0055 diagnostic.

Package feeds

FixPortal.CodeStyle is published publicly on NuGet.org, so consuming public or private repositories need no FixPortal credentials to restore it. FixPortal.CodeStyle.ArchRules is the separate private architecture-rule overlay and still lives on the FixPortal GitHub Packages feed; only consumers that opt into that package need a token:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="github-fixportal" value="https://nuget.pkg.github.com/FixPortal/index.json" />
  </packageSources>
  <packageSourceCredentials>
    <github-fixportal>
      <add key="Username" value="USERNAME" />
      <add key="ClearTextPassword" value="%GITHUB_PACKAGES_TOKEN%" />
    </github-fixportal>
  </packageSourceCredentials>
</configuration>

(Prefer an env-var token over a literal; never commit a PAT.)

Development

Open FixPortal.CodeStyle.slnx in Visual Studio or restore the repository-local tools:

dotnet tool restore

Format C# before committing:

dotnet csharpier format .

Restore, build, pack, and run the package-consumer regression check:

dotnet restore FixPortal.CodeStyle.slnx

dotnet build FixPortal.CodeStyle.slnx --configuration Release --no-restore

dotnet pack FixPortal.CodeStyle.slnx --configuration Release --no-build --no-restore --output artifacts/pack

./tests/Test-PackageConsumer.ps1

The package-consumer script is the repository's executable regression check. It packs the code-style package, proves a deliberately non-compliant consumer fails, formats it, then proves the corrected consumer builds. The fixture project stays out of the solution because it references the temporary package produced by that script. CI runs dotnet csharpier check . to validate formatting without rewriting files.

Releasing

The publish workflow packs both packages, pushes the public FixPortal.CodeStyle package to NuGet.org using trusted publishing, and pushes the private ArchRules overlay to GitHub Packages on a v* tag push (or manual dispatch with an explicit version). To cut a release:

git tag v0.1.1
git push origin v0.1.1

CI uses OIDC trusted publishing for NuGet.org and the repo GITHUB_TOKEN for GitHub Packages — no PAT is needed to publish.

Maintaining the rules

The global config is the rule source of truth. When the house style changes, edit src/FixPortal.CodeStyle/config/FixPortal.CodeStyle.globalconfig, bump the version, and run ./tests/Test-PackageConsumer.ps1 before release. The master .editorconfig in ~/.claude/resources (used by the scaffold-dotnet skill) and the consumer template should be kept in step for documented formatter compatibility entries.