Add semantic functions to the XPath queries of MA0240

Merged
ME
2mo ago
+2486-22

What

This PR adds thirteen functions to the XPath queries of MA0240. Each one works on the node it is evaluated on, whether that node is a syntax node, an operation, or a symbol:

FunctionReturns
implements(type[, format])true when the type of the node implements the interface. The type itself is excluded.
inherits-from(type[, format])true when type is one of the base classes of the node's type
is-assignable-to(type[, format])true when the node's type is type, derives from it, or implements it
has-attribute(type[, format])true when the symbol has an attribute whose class is type or derives from it
attributes() / attributes(nodes)AttributeData elements with ConstructorArgument, NamedArgument and Item children
containing-assembly() / containing-assembly(name)The assembly name, or a case-insensitive test of it
is-from-current-assembly()true when the symbol is declared in the analyzed project
containing-namespace() / containing-namespace(name)The namespace of the symbol, or an exact test of it
overrides(member)true when the symbol overrides member, directly or transitively
implements-member(member)true when the symbol implements that interface member, implicitly or explicitly
is-externally-visible()true when the symbol and all its containing types are public, protected or protected internal
is-captured()true for a local or a parameter used by a lambda or a local function
file-path()The path of the analyzed file, with / separators. It does not need the semantic model

The type argument accepts three formats: MetadataName, DocumentationDeclarationId, and DocumentationReferenceId. The format is detected from the name: a T: prefix means a declaration ID, and a { means a reference ID. An optional second argument overrides the detection. Only reference IDs match specific type arguments. Variance is not considered.

The member argument of overrides and implements-member is either a documentation ID (M:System.Object.Equals(System.Object), which selects one overload) or a qualified name (System.Object.Equals, which selects every overload). The format is detected from the M: prefix.

Why

Until now, a query could only match a type by its exact name. It could not test the inheritance chain, the interfaces, or the attributes of a type. Also, the symbol() function only reaches the symbols declared in the file, so a query could not tell where a referenced symbol comes from.

Notes for reviewers

  • The functions take the semantic model from the XSLT context, not from the navigator. As a result, they also work on the nodes that syntax() returns in operation and symbol queries.
  • A plain syntax query that uses one of these functions is promoted to SemanticSyntax, so it gets the semantic model.
  • The XPath engine does not check Minargs/Maxargs for context functions. ResolveFunction now checks the argument count itself, so MA0241 reports a call with the wrong number of arguments. This also applies to syntax() and symbol(), which previously matched nothing when called with the wrong count.
  • MA0241 reports a type-name format given as a string literal when the format is not one of the three valid names.
  • attributes(nodes) makes it possible to report the attributes themselves. They are reported on the attribute syntax as AttributeData. Attributes that come from metadata can be tested, but they are not reported.
  • file-path() lets an entry apply to some files only. An .editorconfig severity applies to every entry at once. Plain syntax queries now get a context that holds only the syntax tree, so file-path() works in them without requesting the semantic model.
  • is-captured() uses SemanticModel.AnalyzeDataFlow on the body that declares the symbol. The result is cached per body. The parameters of a primary constructor are not considered.
  • docs/Rules/MA0240.md has a new "Semantic functions" section, and docs/Rules/MA0241.md is updated.

Testing

  • 58 new test cases in DoNotUseBannedSyntaxAnalyzerTests. All 270 tests in that class pass on roslyn 4.8, 4.14, 5.0, 5.6 and 5.9.
  • The full roslyn5.9 suite passes (5,070 tests).
  • dotnet run --project src/DocumentationGenerator exits with code 0.