analyzer: file & namespace organization rules (NE0001–NE0003)

[samtrion]

Need & Action (Bedarf & Handlung)

Need: The project layout should be self-describing: a reader (and tooling) should be able to
locate any type from its name and namespace alone. Today nothing enforces that types, files, folders
and namespaces stay aligned, so the tree drifts over time.

Action: Ship the first three NetEvolve.Analyzer rules — all in the Maintainability category —
that enforce file/type/namespace organization, each with an optional code fix where feasible.

ID	Rule	Code fix
NE0001 (#3)	One top-level type per file; file name equals type name (generic-overload exception)	Move type to own file / rename file
NE0002 (#4)	Namespace must match the folder structure relative to RootNamespace	Adjust namespace
NE0003 (#5)	Only one namespace declaration per file	— (diagnostic only, fix TBD)

Sub-issues:

• analyzer: NE0001 — one top-level type per file, file name equals type name #3 — NE0001 One type per file
• analyzer: NE0002 — namespace must match folder structure (RootNamespace-anchored) #4 — NE0002 Namespace matches folder structure
• analyzer: NE0003 — only one namespace declaration per file #5 — NE0003 Single namespace per file

Impact

• Maintainability & discoverability: predictable file locations, smaller diffs, easier reviews.
• Onboarding cost: a one-time, potentially large churn on existing code bases when first enabled —
  mitigated by code fixes and the opt-outs below.
• Consistency with prior art: overlaps conceptually with Roslyn IDE0130, StyleCop SA1649/SA1402
  and Meziantou MA0048; this package unifies them under one configurable, RootNamespace-aware surface.

Global configuration (applies to all three rules)

• Single-file deployment auto-off: the analyzer reads the MSBuild property PublishSingleFile
  (exposed via CompilerVisibleProperty). When true, all three rules stay silent — one-type-per-file
  is meaningless for a single-file publish.
• Explicit override: NetEvolveAnalyzerDisableFileOrganizationRules (bool, default false) force-disables
  all three regardless of PublishSingleFile.

Definition of Done

• Analyzers implemented in src/NetEvolve.Analyzer/Maintainability/
• Code fixes where marked feasible
• Unit tests (Verifiers/) + integration tests (AnalyzerCompiler)
• Diagnostic IDs registered in DiagnosticIds.cs and AnalyzerReleases.Unshipped.md
• Rule docs under docs/rules/NE000x.md
• Coverage gates met (unit >75%, integration >80%, project >90%, patch >95%)

Follow-ups

• analyzer: NE0001 code fix — rename file / move type to its own file #7 — NE0001 code fix (rename file / move type to its own file)