DAS plugins: initial doc for writing rules

Change-Id: I50957b9ae9b19d8cfa5371f5398bc3a001df1661
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/408940
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/analysis_server_plugin/doc/writing_rules.md

@@ -0,0 +1,147 @@
+# Writing Rules
+
+This package gives analyzer plugin authors the ability to write static rules
+for source code. This document describes briefly how to write such a rule, and
+how to register it in an analyzer plugin.
+
+## Declaring an analysis rule
+
+Every analysis rule is declared in two parts: a rule class that extends
+`AnalysisRule`, and a visitor class that extends `SimpleAstVisitor`.
+
+### The rule class
+
+The rule class contains some general information about the rule, like its name
+and the diagnostic or diagnostics that the rule reports. It also registers the
+various syntax tree nodes that the visitor class needs to visit. Let's see an
+example:
+
+```dart
+class MyRule extends AnalysisRule {
+  static const LintCode _code = LintCode(
+    'my_rule',
+    'No await expressions',
+    correctionMessage: "Try removing 'await'.",
+  );
+
+  MyRule()
+      : super(
+          name: LintNames.prefer_void_to_null,
+          description: 'A longer description of the rule.',
+        );
+
+  @override
+  LintCode get lintCode => _code;
+
+  @override
+  void registerNodeProcessors(
+      NodeLintRegistry registry, LinterContext context) {
+    var visitor = _Visitor(this, context);
+    registry.addAwaitExpression(this, visitor);
+  }
+}
+```
+
+Let's look at each declaration individually:
+
+* `class MyRule extends AnalysisRule` - The rule class must extend
+  `AnalysisRule`.
+
+* `static const LintCode _code` and `LintCode get lintCode` - Each rule class
+  must implement either `LintCode get lintCode` or `List<LintCode> get
+  lintCodes`, depending on whether there is only one diagnostic that it can
+  report, or multiple.
+
+  A `LintCode` is the template for each diagnostic that is to be reported. It
+  contains the diagnostic name, problem message, and optionally the correction
+  message. We instantiate a `LintCode` as a static field so that it can also be
+  made const. If the rule needs to report more than one `LintCode`, with
+  different problem messages, then multiple static fields can be declared.
+
+* `MyRule()` - The rule class must have a constructor that calls `super()`,
+  passing along the name of the rule, and a description. Typically this
+  constructor has zero parameters.
+
+* `void registerNodeProcessors(...)` - An analysis rule uses a visitor to walk
+  a [Dart syntax tree][] (we see how the visitor is defined in "The visitor
+  class," below). This visitor is typically named `_Visitor`. This visitor
+  class must be instantiated once in this method. Typically, the instance of
+  the rule class (`this`) and a `LinterContext` object (described below) are
+  passed to the visitor constructor.
+
+  In order for such a visitor's various 'visit' methods to be called, we need
+  to register them, in a `NodeLintRegistry`. Each 'visit' method found on
+  `SimpleAstVisitor` has a corresponding 'add' method in the `NodeLintRegistry`
+  class.
+
+[Dart syntax tree]: https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/doc/tutorial/ast.md
+
+### The visitor class
+
+The visitor class contains the code that examines syntax nodes and reports
+diagnostics. See the [API documentation][SimpleAstVisitor docs] for the
+`SimpleAstVisitor` class to find the various 'visit' methods available for
+implementation. Let's look at a quick example:
+
+[SimpleAstVisitor docs]: https://github.com/dart-lang/sdk/blob/main/pkg/analyzer/lib/dart/ast/visitor.dart#L1841
+
+```dart
+class _Visitor extends SimpleAstVisitor<void> {
+  final LintRule rule;
+
+  final LinterContext context;
+
+  _Visitor(this.rule, this.context);
+
+  @override
+  void visitAwaitExpression(AwaitExpression node) {
+    if (context.isInLibDir) {
+      rule.reportLint(node);
+    }
+  }
+}
+```
+
+Let's look at each declaration individually:
+
+* `class _Visitor extends SimpleAstVisitor<void>` - Each visitor must extend
+  `SimpleAstVisitor`. While the analyzer package provides other Dart syntax
+  tree visitors, using one directly in a rule can result in poor performance
+  and unexpected behavior. The type argument on `SimpleAstVisitor` is not
+  important, as 'visit' return values are not used, so `void` is appropriate.
+* `final LintRule rule` - The rule is the object to which we can report
+  diagnostics (lints or warnings). Several methods are provided, all starting
+  with `reportLint`. The different methods allow for different ranges of text
+  to be highlighted.
+* `final LinterContext context` - The LinterContext object provides various
+  information about the library being analyzed. In this example, we make use of
+  a `isInLibDir` utility.
+* `_Visitor(...)` - Often the constructor just initializes the LintRule and
+  LinterContext fields. Other information can be initialized as well.
+* `void visitAwaitExpression(AwaitExpression node)` - The main component of the
+  `_Visitor` class is the 'visit' methods. In this case, `visitAwaitExpression`
+  is invoked for each 'await expression' found in the source code under
+  analysis. Typically, a 'visit' method like this is where we perform some
+  analysis and maybe report lint(s) or warning(s).
+
+## Registering an analysis rule
+
+In order for an analysis rule to be used in an analyzer plugin, it must be
+registered. Register an instance of an analysis rule inside a plugin's
+`register` method:
+
+```dart
+class SimplePlugin extends Plugin {
+  @override
+  void register(PluginRegistry registry) {
+    registry.registerWarningRule(MyRule());
+  }
+}
+```
+
+Here, the instance of MyRule is registered as a "warning rule," so that it is
+enabled by default. To register an analysis rule as a "lint rule," such that it
+must be specifically enabled from analysis options, use `registerLintRule`
+instead.
+
+TODO(srawlins): Write up and link documentation for this Plugin subclass.