Expand @import directives to explicit importFrom()

[lionel-]

Branched from #1892

This PR expands @import pkg directives to explicit imports in an importFrom(pkg, sym1, sym2, ...) expression. This pins the set of imported symbols between rounds of document(), and prevents users from getting issues at load time when a package update creates a conflict. Instead, new conflicts are deferred until the next time the maintainer documents, where the conflict causes an error that forces the maintainer to resolve it with an except = clause.

Ideally we'd detect symbols actually used by the package with a mechanism like findGlobals(). Until we can do it reliably, possibly with the help of Oak and annotations, I've opted to just import every exports.

[hadley]

What if we introduced a new tag for this? Like @importAll or maybe @importPattern ?

[lionel-]

That would be reasonable, especially as a first step to gain practical experience with the approach, but it would not feel like we're creating a pit of success for our users to fall into :)
I.e. the safe option would not be the default one.

[hadley]

Right, I think we'd still want to change long term, but I worry that it's too big of a change to push through now (even in a minor release). If we used a new tag, I'm happy to merge this and encourage people to use it. (It would also be an interesting place to try and claude code automated patching system)

[lionel-]

@hadley I moved the expansion to a new @importAllFrom tag.

Unlike @import where you can pass arbitrary arguments that get included verbatim in the import() call (e.g. except = c(foo, bar)), we need to actually parse exclusions since we're applying them.

I went for an exclusion syntax that is consistent with the existing @inheritDotParams foo -x -y.

#' @importAllFrom dplyr -filter -lag
#' @importAllFrom rlang -":="

We need the imported package to be installed to figure out the exports. Other features in roxygen2 like inherits degrade to a no-op or fallback when a required package is not installed. Here I preferred to throw a hard error. We also warn when an excluded symbol is not exported.

[hadley]

Would it be better to use select_args_text?

[lionel-]

See last commit:

• Now parses tags with tag_two_part()
• Then parses arguments with select_args_text()
• New class argument threaded through roxy_warn and used to handle failures

[hadley]

It occurs to me that the downside of this approach is that now if rlang removes a symbol, this package will fail to load. With @import (as long as you didn't actually use the symbol) that isn't a problem.

[lionel-]

oooh that's a very good point. This pretty much kills the approach.

The alternative is that once Oak symbol resolution is robust enough, we wrap it in an R package and then use that the way you'd use {globals} to figure out from usage the minimum set of symbols to import.