Report exported member access on @deprecated export

[DartBot]

This issue was originally filed by @seaneagan

---

If you want to stop exporting library A from library B, but you don't want to deprecate library A itself, it would be nice to be able mark the export as deprecated:

@deprecated('Use libraryA.dart directly instead')
export 'libraryA.dart';

Here are some use cases:

Stop exporting something:
  dart-lang/test#53

Split part of a library into a separate library with a temporary re-export:
  dart-lang/test#2326

[bwilkerson]

Removed Priority-Unassigned label.
Added Priority-Medium, Area-Analyzer, Triaged labels.

[nex3]

I'd really appreciate this as well.

[srawlins]

In the following example:

import "package:test/test.dart";

void main() {
  test("String.split() splits the string on the delimiter", () {
    var string = "foo,bar,baz";
    expect(string.split(","), equals(["foo", "bar", "baz"]));
  });
}

What element would get the warning? equals() is an element whose library (package:matcher/matcher.dart) was is available because of its export in package:test/test.dart. Does the warning stick to equals? This makes sense to me, but the wording would have to be very clear, so that users aren't super confused when one day they bump their test package, and their analyzer, and now there are 200 warnings in their tests.

[nex3]

Yes, if test's export of matcher were deprecated, the equals() call would have the warning. I don't think the wording needs to be much more than just "equals() is deprecated"—from the user's perspective, it's the API that's deprecated, and they don't really care where the @deprecated annotation is.

Also, to be clear, test is not actually planning to deprecate its export of matcher.

[bwilkerson]

I suspect that the intent of putting a @deprecated annotation on an export is not to mark the API being exported as being deprecated, but rather to indicate that the export will be removed in a future version and hence users should switch to importing the original source of the API. If that's true, then the message should be something more like: "The function ... should be imported from ... rather than ...".

[lrhn]

I can see both intentions being correct in different cases.
It depends on whether the user is expected to keep using the functionality from the exported library or not. If the exported library is public, and it's not being deprecated itself, then it's likely that the user will begin importing it instead.

If the library is "private" (in lib/src/) then the user will likely not begin using it directly (but may use it indirectly if it's also exported by another public library). In either case, you are in control of the exported library as well, and could potentially make it deprecated.

I think the former case is the more likely, and the message could be "the function .. is deprecated as part of ... library. It may be imported as ... library instead.".

[natebosch]

Do the proposals in #32726 make this any easier?

Other than the phrasing, are there any other technical blockers to allowing deprecated on an export?

[lrhn]

You can put @deprecated on an export, the language allows it. The only issue here is which message the analyzer will show, and when.

libraryExport: metadata 'export' uri combinator* ';'

[natebosch]

This is likely a blocker for #44892

[natebosch]

Funnily enough deprecating the export of matcher for test is the exact reason I have a renewed interest in this feature.

[pq]

(Adding the data-driven-fixes tag here since this will be required for data-driven support of the proposed migration of Matcher APIs from package:test to package:matcher.)

See also: #48997

[pq]

@scheglov: I'm curious if you've had a chance to think any more about this?

[scheglov]

It looks that we need to track provenance for each exported element - declared in the library, or re-exported from other library (where it might be declared, but might also be re-exported), or re-exported from more than one library, although eventually merging into the same library when the element is declared. So, we need chains of provenance.

For this feature we probably would need to look only at the top element of each chain - whether the corresponding export directive is deprecated. And probably checked and reported in ScopeResolverVisitor.visitSimpleIdentifier() when we lookup the name scope.

Such provenance chains might be useful to know how we get for example Offset when we import package:flutter/widgets.dart.

[bwilkerson]

Such provenance chains might be useful to know ...

I'm not opposed to providing more information from the API than we're currently using in server (in fact I think we tend to trim too much from the API), but I'm wondering whether you have a concrete use for this information in mind.

[scheglov]

Theoretically it could be a DAS request that returns such "provenance tree" and IntelliJ could display in a view, something like Class Hierarchy. But I don't have plans to implement it myself :-)