analyzer: NE0002 — namespace must match folder structure (RootNamespace-anchored)

[samtrion]

Part of the file/namespace organization epic #6. Category: Maintainability · ID: NE0002

Need & Action (Bedarf & Handlung)

Need: When the namespace of a type does not follow the folder it lives in, the physical layout and
the logical layout diverge and navigation breaks.

Action: Anchored at the RootNamespace MSBuild property, every folder segment between the project
directory and the file must appear as the corresponding namespace segment. Report a diagnostic when the
declared namespace does not equal RootNamespace + the relative folder path (.-joined).

Non-compliant example

RootNamespace = Geometry
File          = src/Geometry/Shapes/Primitives/Circle.cs

namespace Geometry.Shapes;   // NE0002: expected 'Geometry.Shapes.Primitives'
public sealed class Circle { }

Compliant example

// src/Geometry/Shapes/Primitives/Circle.cs
namespace Geometry.Shapes.Primitives;
public sealed class Circle { }

Category

Maintainability

Default severity

Warning

Code fix

Yes — feasible and in scope. Rewrite the namespace declaration to the expected value (comparable to the
fix shipped for Roslyn IDE0130). References inside the file resolve automatically; cross-file references
are handled by the compiler/rename engine.

Configuration & build properties

• Uses RootNamespace (required anchor). If RootNamespace is unset, fall back to the project/assembly name.
• Global opt-outs from the epic apply.
• Open: should folder segments that are not valid identifiers (e.g. my-folder, leading digits) be
  skipped, sanitized, or reported separately?

Edge cases & exceptions

• Special/"do not map" folders — e.g. Properties, Internal, obj, bin — likely need an ignore list.
• Files directly in the project root map to RootNamespace exactly.
• Multiple namespaces in one file interacts with NE0003 — evaluate per declaration.
• Generated code is skipped.
• Prior art: Roslyn IDE0130 (this rule is the RootNamespace-anchored, configurable variant).