Expose the semantic model to the XPath queries of MA0240

Merged
ME
2mo ago
+1077-40

What

The MA0240 banned syntax queries can now read the semantic model through a semantic XML namespace:

//AddExpression/*[@semantic:TypeConstructedFrom='System.Nullable`1']; Do not add nullable values
//MethodDeclaration[@semantic:ReturnTypeConstructedFrom='System.Threading.Tasks.Task`1']; Return a ValueTask instead
//InvocationExpression[@semantic:SymbolDocumentationId='M:System.Console.WriteLine(System.String)']; Use the logger

Why

The queries were purely syntactic, so banning "an addition on a Nullable<T>" or "a call to Console.WriteLine" required writing a dedicated analyzer. A separate namespace keeps these attributes from clashing with the token attributes, which are named after the properties of the syntax nodes.

The attributes

16 attributes on every element: Type, TypeConstructedFrom, TypeConstructedFromDocumentationId, the three ConvertedType* equivalents, the three ReturnType* equivalents, Symbol, SymbolDocumentationId, SymbolKind, ContainingType, ContainingTypeDocumentationId, HasConstantValue and ConstantValue.

An attribute is absent when there is no value for it, so !=, not(), starts-with() and count() all behave as expected. The names come in three formats, built by the new SymbolNameFormatter since ToDisplayString cannot emit the arity suffix:

  • display name with the type arguments, System.Nullable<System.Int32>
  • metadata name, as GetTypeByMetadataName expects it, System.Nullable`1
  • documentation comment id, T:System.Nullable`1

Notes for the reviewer

  • Cost. The rule only registers a SemanticModelAction when a query actually uses the prefix; otherwise it keeps the SyntaxTreeAction it had. In a file that mixes both, the syntactic entries are evaluated on a navigator built without a semantic model, so they do not pay for the semantic attributes.
  • Typos. MA0241 now reports 'Typo' is not a valid semantic attribute and undefined namespace prefixes, so a typo cannot silently disable a ban. The scanner skips XPath string literals.
  • CreateDeclarationId vs the XML documentation file. CreateDeclarationId appends the return type of every method that does not return void, whereas the compiler only does it for the conversion operators. The emitted id is the documentation one, so it can be copied from a .xml documentation file or a BannedSymbols.txt: M:System.String.Substring(System.Int32), and M:Sample.op_Implicit(Sample)~System.Int32 keeps its suffix.
  • Roslyn 4.8. CreateDeclarationId throws for the symbols that cannot be documented (a parameter, an alias, an array type, a type parameter), where the more recent versions return null. GetDocumentationId allow-lists the symbol kinds, so a local, a parameter, an alias, a lambda and a local function simply have no semantic:SymbolDocumentationId.
  • XPath mechanics were verified before being relied on: namespaced attributes match on a custom XPathNavigator by string.Equals on LocalName/NamespaceURI with no NameTable atomization, an undefined prefix throws at compile time (so it already flows into MA0241 through the existing catch), and the resolver is snapshotted into the compiled expression, so it survives the Clone() the static QueryCache relies on.
  • GetTypeInfo/GetSymbolInfo/GetConstantValue/GetDeclaredSymbol never throw for an arbitrary SyntaxNode; the only preconditions are non-null and same-tree, both guaranteed by the navigator. A test runs a semantic: query over a file exercising ~117 node kinds to prove it.

Tests

28 tests added to DoNotUseBannedSyntaxAnalyzerTests, one per attribute plus the declared-symbol fallback, the reported name and span of a semantic attribute, a file mixing syntactic and semantic entries, the node-kind robustness sweep, and the MA0241 cases.

The full suite passes on all five Roslyn versions (23,980 tests). dotnet run --project src/DocumentationGenerator reports no change.