Add MA0240: Do not use banned syntax, and MA0241 for invalid entries
Merged
ME
2mo ago+1348+1348+0123456789012345678901234567890123456789-0-0-0123456789
Adds MA0240, a rule that reports the syntax listed in a BannedSyntaxes.txt file, each with an optional message. A project can use it to ban constructs such as goto, primary constructors or nested conditional expressions, and tell users what to use instead, without writing its own analyzer. The format follows BannedSymbols.txt from Microsoft.CodeAnalysis.BannedApiAnalyzers.
The rule is enabled by default as a warning. At the start of each compilation it checks for a BannedSyntaxes.txt or BannedSyntaxes.*.txt additional file, and if there is none it registers no other actions. Projects that don't use the rule pay only that file-name check.
# Lines starting with '#' are comments
GotoStatement; Use structured control flow instead
//ClassDeclaration/ParameterList; Do not use primary constructors
//ConditionalExpression//ConditionalExpression; Do not nest conditional expressions
//*[count(ParameterList/Parameter) > 5]/@Identifier; Use a parameter object
This reports, for example: The syntax 'ParameterList' is banned: Do not use primary constructors.
File format
- Each line is a query, optionally followed by
;and a message. - The query and message are split at the first
;that isn't inside a quoted string in the query. #starts a comment.//can't be used for comments, asBannedSymbols.txtdoes, because it starts most XPath queries.BannedSyntaxes.txtandBannedSyntaxes.*.txtfiles are read, so a file shared by several projects can be combined with one specific to a project.
Queries
- Kinds: a line that is just a kind name, or
//followed by a kind name, is matched without XPath. All such lines are checked together in one pass over each file. In XPath a bare name would only match the file's top node, so treating it as a kind loses nothing. Names are case-sensitive, to match XPath. - XPath: other lines are XPath 1.0 queries.
SyntaxNodeXPathNavigatorpresents the syntax tree as XML to .NET's built-in XPath engine (System.Xml.XPath), without building an XML document:- Each node is an element named after its kind.
- Each token property (
Identifier,Keyword,Modifiers…) is an attribute holding the token's text. - When a query selects an attribute, the diagnostic covers those tokens.
- Duplicates: a construct banned by two lines with different messages gets both messages. The same message is reported once, even when it comes from several lines or files.
- Caching: each file is parsed once, cached by its
SourceText. Each query is compiled once and kept in aBoundedCache, and each evaluation uses a clone of the compiled expression, because compiled expressions are not thread-safe. The navigator checks the cancellation token as it moves through the tree.
Invalid lines (MA0241)
- These are reported on the line in the banned-syntax file itself, via
RegisterAdditionalFileAction. - This covers unknown kinds, XPath syntax errors, queries that don't select nodes, and unknown functions (detected by a trial evaluation).
- The file's other lines still apply.
- These are reported by a separate rule, MA0241 ("The banned syntax entry is not valid"), enabled by default as a warning, so they can be configured independently of MA0240.
Package
build/Meziantou.Analyzer.propsadds the closestBannedSyntaxes.txt(project folder, then parent folders) toAdditionalFiles, usingGetDirectoryNameOfFileAbove.MeziantouIncludeBannedSyntaxesFile=false, set inDirectory.Build.props, turns this off.- If a project also adds the file itself, the analyzer ignores the duplicate path.
- Checked with
dotnet msbuildevaluations covering: a file in a parent folder, a file in the project folder taking priority, the opt-out property, and no file.
Testing
- The analyzer builds for all five Roslyn versions, and the pack project builds.
- The full test suite passes on Roslyn 5.9 (4,827 tests).
- The 30 MA0240 tests pass on Roslyn 4.8.
- The RuleHelpUri, Internals and MA0220 tests pass on 5.9.
- The MA0240 tests have not been run on Roslyn 4.14, 5.0 or 5.6; CI covers those.