Review impact of new format for `#line` pragma on existing rules

[sharwell]

[sharwell]

Audit by Deep Research

Impact of C# 10 #line Pragma on StyleCopAnalyzers

C# 10 introduced an enhanced #line directive format with span and file mapping. This affects how StyleCopAnalyzers interpret line numbers, columns, and file names, and how they should treat hidden regions.

SA1025 – Code must not contain multiple whitespace characters in a row

Current Behavior

• Uses SyntaxTree.GetMappedLineSpan(...) and checks if whitespace appears at column 0 to determine if it’s leading indentation (which is allowed).
• Under enhanced #line, the mapped column may be non-zero even for leading indentation if a column offset is applied.

Problem

• Using mapped columns means indentation in regions mapped with an offset can be misinterpreted as “multiple whitespace in a row” and incorrectly flagged.

Required Changes

• Use unmapped positions for this rule’s logic:

  • Replace GetMappedLineSpan with GetLineSpan (or disable preprocessor mapping).
  • Base the “start-of-line” check on physical source column, not mapped column.

Documentation & Tests

• Document that SA1025 evaluates whitespace based on physical layout, ignoring #line column offsets.

• Tests:

  #line (5,5)-(5,10) "File.cs"
      int x = 0;
  #line default

  Ensure no SA1025 diagnostic is reported for indentation on int x = 0;.

---

SA1649 – File name must match type name

Current Behavior

• SA1649 uses context.Tree.FilePath to compute the actual file name and compares it to the first type’s identifier.
• Diagnostics are emitted on the type’s identifier token, and Roslyn’s diagnostic mapping uses #line to remap locations.

Problem

• With #line 1 "GeneratedCode.cs", diagnostics from SA1649 may appear as if they are for "GeneratedCode.cs" even when the physical file is different (e.g., ActualFile.cs).
• This can confuse users when #line remaps the file name for diagnostics.

Required Changes

• Keep computing expected vs actual filename using the real file path.

• For location:

  • Consider constructing diagnostic locations using an unmapped span (e.g., an empty span at the start of the file) via Location.Create(sourceTree, span).
  • This should tie the diagnostic to the physical file rather than the remapped filename.

Documentation & Tests

• Clarify in docs that SA1649 checks physical file names and is not fooled by diagnostic remapping.

• Tests:

  // ActualFile.cs
  #line 1 "DifferentName.cs"
  public class NotMatching { }
  #line default

  Ensure SA1649 reports a mismatch for ActualFile.cs, not “DifferentName.cs”.

---

SA1633 and Related File Header Rules (SA1634–SA1641)

Current Behavior

• File header logic skips directive trivia (trivia.IsDirective) when searching for the first XML comment.
• Directives such as #pragma, #nullable, and #line may appear before the header without causing SA1633 (“file has no header or not at top”) to trigger.

Interaction with #line

• A #line directive at the top of a file is treated as a directive and ignored while finding the header.
• If no header is found, SA1633 reports a missing header at the file start (before any mapped sections).

Required Changes

• No implementation changes necessary.

Documentation & Tests

• Docs: clarify that compiler directives (including #line) may appear before the header comment without violating SA1633.

• Tests:

  • File starting with #line 1 "X.cs" followed by a valid header → no SA1633.
  • File starting with #line 1 "X.cs" and no header → SA1633 reported at file start.

---

SA1102–SA1105 – Query Clause Line Spacing Rules

Current Behavior

• SA1102–SA1105 analyze LINQ query clause positions.

• They explicitly avoid treating lines with directives as blank lines:

  • A check like !token2.LeadingTrivia.Any(trivia => trivia.IsDirective) prevents SA1102 from firing when a directive is present between clauses.

Interaction with #line

• Enhanced #line is still represented as LineDirectiveTrivia (IsDirective == true), so existing checks apply.
• Query clause rules use physical source positions (GetLineSpan), not mapped positions, so line mappings don’t interfere.

Required Changes

• No code changes required.

Documentation & Tests

• Docs: mention that any directive (including #line) between query clauses is treated as content, not a blank line.

• Tests:

  var q =
      from x in xs
      select x
  #line default
      where x > 0
      select x;

  • Confirm no SA1102 “blank line between query clauses” is raised.

---

SA1507, SA1517, SA1518 – Blank Line Rules

• SA1507: no multiple blank lines in a row.
• SA1517: no blank lines at start of file.
• SA1518: no blank lines at end of file.

Current Behavior

• Blank-line rules treat directive trivia as content:

  • A line with only #line is not a blank line.
  • Multiple consecutive directives do not count as multiple blank lines in a row.

Interaction with #line

• #line directives on their own lines are not considered blanks.
• Leading/trailing lines with #line are considered content; SA1517/SA1518 do not flag them.

Required Changes

• No implementation changes.

Documentation & Tests

• Docs: optionally note that lines containing only directives are not “blank”.

• Tests:

  • Two consecutive #line default directives should not trigger SA1507.
  • #line at top followed by a blank line and then code: SA1517 should not fire (the first content is the directive).
  • #line at bottom with no trailing blanks should be treated as last content; SA1518 should not fire.

---

SA1508 / SA1509 – Blank Line Around Braces

• SA1508: a closing brace should not be preceded by a blank line.
• SA1509: a closing brace should not be followed by a blank line (or similar rule, depending on numbering).

Interaction with #line

• A #line directive between braces is treated as content:

  if (condition)
  {
      DoWork();
  #line default
  }

• The line with #line is not blank; there is no “blank line before the brace”, so SA1508 should not fire.

• Similarly, a #line immediately following a closing brace does not count as a blank line for SA1509.

Required Changes

• None; current logic that treats directives as non-blank content should handle this correctly.

Tests

• Add tests with #line immediately before/after closing braces to ensure SA1508/1509 do not mis-report.

---

Consideration: Skipping Analyzers in #line hidden Regions

Background

• #line hidden marks regions where compiler diagnostics are suppressed.
• Analyzer diagnostics are not automatically suppressed unless they explicitly check for hidden positions.

Current Behavior

• StyleCopAnalyzers do not currently skip hidden regions by default.
• This can cause warnings in code that the author intended to hide (e.g., generated code wrapped in #line hidden).

Recommendation

• Consider suppressing StyleCop diagnostics inside #line hidden regions.

Implementation Approach

• Use Roslyn APIs or utilities to detect hidden positions:

  • Inspect location.GetLineSpan().IsHidden if available.
  • Or use a helper that emulates IsHiddenPosition semantics.

• Before reporting a diagnostic:

  var span = location.GetLineSpan();
  if (span.IsHidden)
  {
      // Skip reporting diagnostic
  }

Documentation & Tests

• Docs:

  • State that StyleCopAnalyzers will skip diagnostics in #line hidden regions (if implemented).
  • Alternatively, explicitly mention if hidden regions are not skipped, so users know what to expect.

• Tests:

  int visible = 0;
  #line hidden
  int hiddenCode = 0; // style violation here should be ignored
  #line default
  int visible2 = 0;

  Ensure only visible and visible2 are checked; violations inside the hidden region must not be reported.

---

Summary

For C# 10’s enhanced #line directives:

• SA1025 must switch to using unmapped positions to avoid misinterpreting indentation.
• SA1649 may adjust diagnostic locations to avoid confusion when file names are remapped.
• Header rules, query clause rules, and blank-line/layout rules mostly require no logic changes but benefit from documentation clarifications and tests.
• Hidden regions (#line hidden) should be considered for analyzer suppression to better match user expectations for generated or intentionally hidden code.

Sources

• C# 10 enhanced #line directive spec
• SA1025CodeMustNotContainMultipleWhitespaceInARow.cs
• SA1649FileNameMustMatchTypeName.cs
• Enhanced #line directives – C# 10 proposal
• FileHeaderHelpers.cs
• SA110xQueryClauses.cs
• SA1507CodeMustNotContainMultipleBlankLinesInARow.cs
• SA1517CodeMustNotContainBlankLinesAtStartOfFile.cs
• SourceTextExtensions.cs (hidden position helpers)