Feature: utilitiescs-nullable-helperclasses

[drmoisan]

• Work Mode: full-feature

Problem / Why

The CI nullable gate (repaired by PR #361 to use msbuild /t:Rebuild ... /p:Nullable=enable /p:TreatWarningsAsErrors=true) now performs a genuine recompile and surfaces pre-existing
CS86xx nullable-reference-type diagnostics that were previously masked. The
UtilitiesCS/HelperClasses/ directory tree (approximately 43 .cs files, including FileSystem,
ThemeHelpers, and root helper classes) carries such pre-existing nullable debt. These are shared
helpers consumed across module boundaries; their nullability annotations become contracts that
downstream epic features (OutlookObjects, EmailIntelligence, Dialogs clusters) consume.

Proposed Behavior

Remediate the pre-existing nullable-reference-type debt across UtilitiesCS/HelperClasses/
using a per-file #nullable enable opt-in:

• Add a #nullable enable pragma to each remediated file and bring that file to zero CS86xx
  diagnostics under the pragma.
• Do NOT enable nullable at the project or solution level. UtilitiesCS.csproj has no
  <Nullable> element and must keep none.
• Annotation and null-safety only: nullable annotations (?), null guards, null-forgiving
  operators only where justified, and null-flow corrections. No behavior changes, no refactors,
  no API redesign, no feature work.
• Keep public signatures behavior-compatible; annotate to reflect actual null behavior so the
  annotations serve as accurate downstream contracts.

Acceptance Criteria

• Every .cs file under UtilitiesCS/HelperClasses/ that emits CS86xx carries
  #nullable enable and compiles with zero nullable diagnostics under the per-file pragma with
  TreatWarningsAsErrors.
• No project-level <Nullable> element is introduced in UtilitiesCS.csproj.
• No behavior change; existing tests still pass; no coverage regression on changed lines.

Constraints & Risks

• Follow the repo C# toolchain order (csharpier -> msbuild analyzers/codestyle -> msbuild
  nullable with TreatWarningsAsErrors -> vstest with coverage). MSTest + Moq + FluentAssertions
  for any test work.
• Annotations become cross-module contracts; incorrect annotations could propagate incorrect
  null assumptions to Wave 1 dependents (outlook-folder-store, outlook-mailitem-item,
  dialogs-misc).
• The .claude/rules/csharp.md toolchain documents forcing /p:Nullable=enable globally, which
  conflicts with the per-file opt-in convention. This conflict is flagged for the maintainer at
  the epic level (capstone child), not resolved here.

Test Conditions

• Existing MSTest suite for UtilitiesCS still passes post-annotation.
• No coverage regression on changed lines.
• Nullable gate (/t:Rebuild /p:Nullable=enable /p:TreatWarningsAsErrors=true) passes for
  the opted-in files.

Source

From: docs/features/potential/2026-07-18-utilitiescs-nullable-helperclasses.md