Review impact of top-level statements on existing rules

[sharwell]

https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/program-structure/top-level-statements

[sharwell]

Audit by Deep Research

Audit of StyleCopAnalyzers Rules for C# 9 Top-Level Statements Support

C# 9 introduced top-level statements, allowing executable code at the root of a file without an explicit Main method or Program class. This audit focuses on the impact of that feature on StyleCopAnalyzers rules, specifically where top-level statements required analyzer, documentation, or test updates.

---

Rules Needing Implementation Changes

SA1200 – Using directives placement

Problem

SA1200 expects using directives to appear either inside or outside the namespace based on configuration. In a top-level statements file (which has no namespace), all using directives must appear at the top of the file by language design. Initially, SA1200 would incorrectly flag every top-level using as a violation.

Change

• SA1200 was updated (see fix Fix SA1200 handling of top-level statements #3261) so that it recognizes top-level programs.
• When no namespace declaration is present, SA1200 now treats using directives at the top of the file as valid in the global scope.
• For the single top-level program file, using directives appearing before any top-level code are always allowed.

SA1516 – ElementsMustBeSeparatedByBlankLine

Problem

SA1516 requires a blank line between adjacent elements (e.g., between a method and a property). With top-level statements, new patterns arise:

Console.WriteLine("Hello");

class C { }

The block of top-level statements followed immediately by a type (class, struct, namespace, etc.) must be treated as adjacent elements. Originally, SA1516 had a known bug in this scenario and didn’t consistently require or properly locate the blank line.

Change

• SA1516 now treats the block of top-level statements as a single “element”.
• When a type or namespace declaration follows top-level code, SA1516 expects a blank line between them.
• The diagnostic location was corrected so the warning highlights the right position in top-level program files.

SA1649 – File name must match first type name

Problem

SA1649 enforces that a file’s name matches its first top-level type (e.g., MyClass.cs contains class MyClass). Top-level programs can:

• Have no type at all (only statements), or
• Have top-level statements followed by a type.

Originally, this could lead to false positives or crashes when no type was present.

Change

The rule logic was updated so that:

1. It finds the first top-level type in the file (if any).
2. If no top-level type exists (only top-level statements), it skips the file for SA1649.
3. If a type appears after top-level statements, that type is treated as the “first type” and used for the file-name comparison as usual.

The implicit compiler-generated Program type for top-level statements is not visible to the analyzer and is not considered by SA1649.

---

Rules Needing Documentation Changes

SA1200 – Using directives placement

Docs should explicitly describe behavior for top-level statement files:

• In a C# 9 top-level program (no namespace), using directives at the top of the file are correct and do not violate SA1200.
• If stylecop.json is configured with usingDirectivesPlacement = "insideNamespace", this setting is effectively overridden for the single top-level statements file, since all using directives must be global there.
• A note like:

For top-level statement files, using directives appearing before any code are acceptable and do not violate SA1200.

would clarify behavior for users following minimal Program.cs patterns.

SA1516 – ElementsMustBeSeparatedByBlankLine

Docs should mention top-level statements explicitly:

• Treat “the block of top-level statements” as a code element.
• A blank line is expected between the end of that element and the first following type or namespace.

Example:

Console.WriteLine("Hello, world!");
// SA1516 expects a blank line here
class C
{
}

SA1649 – File name vs. first type name

Docs should explain SA1649 in the presence of top-level statements:

• If a file contains only top-level code and no type, SA1649 does not apply.
• If the file contains top-level statements and then a type (e.g., class Helper), that type is used for the file-name comparison.

Example behaviors:

• Program.cs containing only top-level statements → no SA1649.
• Utils.cs with top-level statements followed by class Helper → SA1649 expects the file to be named Helper.cs (or the type moved to a separate file).

---

Rules Needing New or Revised Tests

SA1200 – Using directives placement

Add tests to cover:

• Top-level file with using System; at the top and only top-level code → no diagnostic.
• Verify behavior with usingDirectivesPlacement set to both insideNamespace and outsideNamespace in top-level programs.
• Ensure no regressions or spurious diagnostics in top-level files.

SA1516 – ElementsMustBeSeparatedByBlankLine

Tests should validate:

• Top-level code immediately followed by a type without a blank line → SA1516 reported.
• Same file with a blank line between them → no diagnostic.

Also include scenarios with assembly attributes and top-level statements:

[assembly: System.Reflection.AssemblyVersion("1.0.0.0")]

Console.WriteLine("Hello");

Verify that SA1516 behaves consistently for attributes, top-level code, and following types.

SA1649 – File name vs. first type

Add tests for top-level scenarios:

• Program.cs with only top-level statements → no SA1649.
• Utils.cs with top-level statements and then class Helper → SA1649 expected.
• Files where the first type is an enum or delegate (e.g., MyValues.cs with enum MyValues) both with and without top-level statements.

Ensure:

• SA1649 ignores files with no type.
• SA1649 enforces the rule when a type appears after top-level code.
• The implicit Program class generated for top-level statements is never used as the “first type”.

---

Rules Unaffected by Top-Level Statements

Most StyleCopAnalyzers rules are unaffected by top-level statements:

• Spacing rules (SA1000–SA102x): Spacing is independent of whether code is in Main or at the top level.
• Readability & maintainability rules (SA1100–SA112x, SA1400–SA1499): Continue to work as before. Some rules are naturally moot for global code (e.g., SA1101 relies on this, which doesn’t exist at top level).
• Ordering rules within types (SA1201–SA1214, SA1216, etc.): Only consider types’ members, not top-level statements.
• Naming rules (SA1300–SA131x): Only apply to user-declared symbols, not the implicit Program type.
• Documentation rules (SA1600–SA1650 series): Continue to apply to explicit types and members; they do not apply to the implicit Main.
• Layout rules (SA1500–SA1515, SA1517+): Aside from SA1516, they operate on blocks and braces in the same way, whether code is top-level or inside a method.

---

Summary

Top-level statements primarily affect rules that care about file structure and element boundaries:

• SA1200 needed to understand using directives in a top-level file.
• SA1516 needed to treat the top-level statement block as an element.
• SA1649 needed to handle files with no explicit type.

Once these changes, docs, and tests are in place, StyleCopAnalyzers fully supports C# 9 top-level statements without false positives or omissions.