analyzer: NE0003 — only one namespace declaration per file

[samtrion]

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

Need & Action (Bedarf & Handlung)

Need: A file that declares more than one namespace hides types from the name↔location mapping the
other two rules establish, and complicates NE0001/NE0002.

Action: Report when a single file contains more than one namespace declaration (block-scoped or a mix
of block- and file-scoped). Exactly one namespace per file.

Non-compliant example

// File: Types.cs
namespace Geometry.Shapes    // NE0003: more than one namespace declared in this file
{
    public sealed class Circle { }
}

namespace Geometry.Solids
{
    public sealed class Sphere { }
}

// File: src/Geometry/Shapes/Circle.cs   (RootNamespace = Geometry)
namespace Geometry            // NE0003: nested namespace declaration must be resolved
{
    namespace Shapes
    {
        public sealed class Circle { }
    }
}
// Fix flattens to the folder-derived namespace 'Geometry.Shapes' (see NE0002)

Compliant example

// File: Circle.cs
namespace Geometry.Shapes;
public sealed class Circle { }

Category

Maintainability

Default severity

Warning

Code fix

Yes — two shapes:

1. Nested namespaces (namespace A { namespace B { } }) must be resolved (flattened). The fix
   collapses the nesting into a single declaration whose value matches the folder structure per NE0002
   (i.e. RootNamespace + relative folder path) — not merely the concatenated A.B.
2. Multiple sibling namespaces in one file: splitting per namespace (and per type, per NE0001) is the
   harder case and is handled by the shared "move type to file" fix tracked with NE0001.

Configuration & build properties

• Global opt-outs from the epic apply (auto-off on PublishSingleFile, plus
  NetEvolveAnalyzerDisableFileOrganizationRules).

Edge cases & exceptions

• The global namespace (no declaration) plus one declared namespace: decide whether that counts as
  "multiple". Proposed: a single declared namespace with no top-level members outside it is compliant.
• Nested namespaces (namespace A { namespace B { } }) are always reported and must be resolved: the
  fix flattens them to a single declaration that matches the folder-derived namespace (see NE0002). The
  flattened value is the folder structure, not the literal A.B concatenation.
• Generated code is skipped.