[analyzis_server_plugin] Constraints explanation on tutorials

[FMorschel]

Since we actually run on DAS, I don't think the constraints given on pubspec.yaml would be the constraints for running an analysis_server_plugin. But please help me understand this better if I'm wrong.

Over at writing a plugin or at using a plugin, we have no indication of how to display Dart constraints on our package. Or if we are expected to analyse a specific package (like Flutter), our constraints on it.

We should probably have this information somewhere so our plugin devs know how to explain this to their users.

CC @srawlins @bwilkerson

[srawlins]

Since we actually run on DAS, I don't think the constraints given on pubspec.yaml would be the constraints for running an analysis_server_plugin. But please help me understand this better if I'm wrong.

I think this is wrong. The analyzer plugin isolate is run in its own isolate group, with its own pubspec.yaml file, which is generated, and "pub version solve." The only constraint that DAS puts on the isolate's versions is a version constraint on the analysis_server_plugin package. Dart 3.10.0 will require analysis_server_plugin: ^0.3.0. We could probably document this somewhere, but I'm not sure where.

[FMorschel]

I guess my specific questions would be:

• If my plugin wants to analyse a specific version (or range of versions) of a package, how do I make sure the constraints (on the analysed project) are correct?
• Could I notify my user that this will not work if they have a version I don't support analysing?
• If someone using an old Flutter version with Dart 3.6, for example, wanted to use my plugin, could they?
• As you described, how do I say that I'd need to upgrade my versions for the new DAS to be able to run my plugin correctly?

Things like this would be my concerns as an author.

We could probably document this somewhere, but I'm not sure where.

I guess the first two questions are more specific to the plugin, and the other two would be tied to Dart versions, but yes, where to display this is a good question, which I don't have an answer to yet either.

[srawlins]

If my plugin wants to analyse a specific version (or range of versions) of a package, how do I make sure the constraints (on the analysed project) are correct?

Ooh. I don't think there is an easy way.

Could I notify my user that this will not work if they have a version I don't support analysing?

If you can figure out that you can't analyze the version currently in play, then you could produce a diagnostic (with an analysis rule).

If someone using an old Flutter version with Dart 3.6, for example, wanted to use my plugin, could they?

They cannot.

As you described, how do I say that I'd need to upgrade my versions for the new DAS to be able to run my plugin correctly?

Hmm, we show the pub upgrade error saying that pub can't solve the version constraints. We could perhaps produce a diagnostic in the analysis options where the plugin (with its constraints or path) are specified.

Things like this would be my concerns as an author.

All good questions.

[FMorschel]

you could produce a diagnostic (with an analysis rule).

Can I report on a non-dart file with the new plugin?

Say I wanted to warn on the version for the package dependency at pubspec.yaml, or even if we wanted to verify that those configurable rules (#61755) are valid.

If we can't, that might be a good issue to open, so we keep track of that.

If someone using an old Flutter version with Dart 3.6, for example, wanted to use my plugin, could they?

They cannot.

What is the minimum version of the Dart SDK so this new plugin works? Is this documented somewhere?

[bwilkerson]

One general approach to keep in mind: I think it would be reasonable to add some plugin-developer-oriented pages to the server's insights pages. These could display the information that we think would be useful.

• If my plugin wants to analyse a specific version (or range of versions) of a package, how do I make sure the constraints (on the analysed project) are correct?

Are you concerned about the dependency range in the package being analyzed? If so, then you'd need to find the pubspec.yaml file, read and parse it, and then extract the range yourself.

But I do have to wonder whether this is a problem that will arise much in practice. The analysis server handles every version of every third-party package (as long as they work with a supported version of the SDK, which is quite a large range), and there's very little code that deals with version information. Do you have an example of where you would need this kind of support?

[FMorschel]

Are you concerned about the dependency range in the package being analyzed? If so, then you'd need to find the pubspec.yaml file, read and parse it, and then extract the range yourself.

Can I do this with an AnalysisRule? Or does it only support .dart files? I suspect so because of the resolved units we get. In that case, how can I get a DiagnosticReporter to warn on the package version for the .yaml files?

But I do have to wonder whether this is a problem that will arise much in practice. The analysis server handles every version of every third-party package (as long as they work with a supported version of the SDK, which is quite a large range), and there's very little code that deals with version information. Do you have an example of where you would need this kind of support?

I'm not concerned that my plugin won't be able to analyze the package. I'm concerned about API evolution. Say you have a 1.0 version of a package with certain classes and methods. If they get refactored into something different later in version 2.0, then the rules I wrote for that structure can be removed, and I'd need to handle the new version. Or if I want to maintain both, I'd need a way to know which version the package is being depended on, to enable only the relevant rules.

I mean, the only .dart analysis is fine as long as we keep it to code structure and things like that (which the SDK does today). But if we want to build plugins for packages on how to use them, this will be a concern.

[srawlins]

Can I report on a non-dart file with the new plugin?

Ooh I think you cannot report on pubspec or analysis options files yet. I've filed #61881 for this.

What is the minimum version of the Dart SDK so this new plugin works? Is this documented somewhere?

We can say Dart 3.9 Beta 1 or Dart 3.10 stable. I don't believe it is documented anywhere.

[FMorschel]

I'd say we should probably indicate in the changelog what running SDK version expects the current package version. Since people will probably look there for understanding the changes made. Maybe even create a test to ensure that when we change the minimal version on the SDK we remember to update there.

So when we launch a new version our users don't go ahead to upgrade their constraints if their running SDK won't allow that.