`analysis_server_plugin` to warn when matchers are being used agains a non-expected type

[FMorschel]

Based on #2461, I'd like to request we have a way of adding an annotation to Matchers that, when used, will trigger a lint if the type being matched against is not expected.

Something like:

import 'package:test/test.dart';

void main() {
  test('MyMatcher description', () {
    expect(2, myMatcher);
    expect('2', myMatcher); // This would trigger a lint because the type `String` is not on the list of types for the annotation
  });
}

final myMatcher = MyMatcher();

@Annotation([int])
class MyMatcher extends Matcher {
  @override
  Description describe(Description description) =>
      StringDescription('an integer');

  @override
  bool matches(item, Map<dynamic, dynamic> matchState) =>
      item is int && item > 0;
}

/// Consider built-in
class Annotation {
  const Annotation(List<Type> types);
}

@srawlins' #2461 (comment):

For first-party matchers in the matcher package, I don't think it would be worth the extra complexity. So the feature would be for custom matchers implemented outside of the matcher and test packages.

[srawlins]

I like this idea. I can't say whether it is high impact. The suggested syntax (@Annotation([int])) is probably fine. One drawback is you cannot specify record type literals or function type literals (they would have to be specified in a typedef). You could use type arguments to specify those syntaxes inline, but then you lose the list feature (we don't have "default" type arguments).

[FMorschel]

We could if we had a placeholder-like class/method.

Say we create:

class const TypeHolder<T>() {}

And that list accepts only TypeHolder, we can test for the given argument to it.

@Annotation([TypeHolder<int?>(), TypeHolder<void Function()>()]);

[eernstg]

Why not just use @Annotation([int, TypeOf<(int, int)>]) where typedef TypeOf<X> = X;?

[FMorschel]

We could, and that obviously has some advantages, but I'd vote in favour of consistency. Having a single way to express all types. Even though we'd have to write a bit more, it would be easier to explain to users than "Some of the time, you may need this typedef and use the type argument", I think.

[eernstg]

You could just recommend that TypeOf<T> is used rather than T, even in the case where the syntax of T is such that it is already an expression.

[FMorschel]

Sure, but we can't know for sure that our users will follow it, and some will probably find this in some other code and skip the docs, going straight to the type system (which will show them Type), probably assuming TypeOf is declared in the project they found the annotation being used.

I'm not too in favour of either, just explaining my thoughts. If you dislike the idea, we can surely use the typedef.