feat: add meta property and rollupVersion to plugin context

[shellscape]

This PR contains:

• bugfix
• feature
• refactor
• tests
• documentation
• metadata

Breaking Changes?

• yes
• no

If yes, please describe the breakage.

Please Describe Your Changes

This resolves #1374 by changing the signature of the options hook to accept a second parameter named meta which currently will contain { version: string }. by adding a meta property to a plugin context (this within hooks), which contains rollupVersion as suggested.

I ended up piggy backing on the test that checks the options hook can effect inputOptions. If there's a better place for that, I'm all for it. which checks validity of buildStart and buildEnd hooks. The filename is just plain old hooks, so it seemed an apt place for them. (This is probably a case of the tests needing a bit of spring cleaning.)

[guybedford]

Thanks for taking a look at this.

It might be more convenient to have this information available to all hooks through the plugin context - this.rollupVersion or similar perhaps?

[shellscape]

I can definitely take a look at going that route. I'm a big fan of the meta property name to contain non-essential metadata. Any objection to that naming?

[guybedford]

I'd be happy with that.

[shellscape]

@guybedford changes made, tests passed locally. ESLint was responsible for the whitespace changes in hooks/index.js and they appear legitimate changes.

[guybedford]

Looks good to me.

What else do you see this meta containing in future?

[guybedford]

This should no longer be needed.

[shellscape]

Ah that sneaky bugger. Uno momento por favor.

[shellscape]

Lot's of opportunity for hypotheticals, might include:

• metrics of varying kinds (plugin run times, cache metrics, ...)
• plugin info we could populate automatically, which could be used in future custom build reports/reporters

Mostly I've used meta to future-proof as a home for static bits of information, so as not to pollute (used in loose terms) a namespace or object properties. I'm not held strongly to using that and wouldn't push back on tacking rollupVersion straight onto the context, if meta doesn't sit right.

[guybedford]

metrics of varying kinds (plugin run times, cache metrics, ...)

Currently we have a getTimings method provided on the bundle result.

Not at all debating - just trying to think about what info might be provided so that we can make sure the convention can scale well.

[shellscape]

No worries. We can let this marinate for a bit too.

[lukastaegert]

Very nice, this could really help in migrating plugins to new APIs by allowing them to support an old API in parallel. Some thoughts and questions:

• How do we want to decide in the future if stuff is put onto meta or directly onto the plugin context? For now, one possible distinction could be that meta is for (more or less static) data while the context is for API functions?
• In this spirit as a hypothetical example, one way to make timings available to plugins here could be: If the perf option is provided, meta contains an additional property that contains the currently collected timing information and which is mutated each time new timings are added.
• How do we want to handle documentation? This should be documented soon, otherwise we might forget about it. This means we should be sure enough about this because people will start using it. For reference, this is where this information is collected at the moment: https://github.com/rollup/rollup/wiki/Plugins#plugin-context

[tivac]

I really hate that the plugin API lives in the wiki, because I always forget that the wiki even exists now that it's been 99% deprecated.

[shellscape]

@tivac I'm absolutely planning to merge that to the main docs repo this week.

@lukastaegert I agree that it should only contain static data. That's always my intention when I use that moniker. And the ideas around perf data seem reasonable to me. I'll also update the wiki before this is merged. (and following, will be a PR on the docs site to move the plugin info)

Can we get a second approval to knock this one home?

[lukastaegert]

Can we get a second approval to knock this one home?

You totally got my approval, just wanted to clear this up before merging this. That being said, please merge at your own discretion 😉

[shellscape]

Thanks @lukastaegert I'll work on the documentation later tonight or tomorrow. Keep an eye out for that one.