Add a header option to combining_builder

[natebosch]

The header option was removed from PartBuilder because individual builders no longer control the entire end file at .g.dart - it's now a concatenation of all .something.g.part files which might be produced by other builders as well. The ordering isn't controllable. Since we don't know which file will be first a "header" might not end up at the top of the resulting file.

We could add a header option to source_gen|combining_builder. I was originally opposed to doing this because:

1. I only saw it being used for copyright headers and I didn't think that was a good justification.
2. It's really unfortunate that a user who only knows about the package they are directly depending on would need to learn about a new builder they aren't specifically asking for in order to configure a header, and the usage of source_gen and the combining builder becomes an implementation detail that the end user depends on.

I've now heard a new use case which is adding //ignore_for_file: comments for opt in lints that the builder authors aren't aware of.

I still think (2) is a bummer but this is a pretty good reason to want a header. Technically these comment don't need to be at the top of the file and we could put them back as "section headers" in the individual parts which might end up anywhere in the result file, but I'm not sure that's much better than having to learn about a new builder name to configure the header on.

cc @kevmoo who was right about this from the beginning.

[natebosch]

I'd also prefer if there were a better way to silence these lints in the analyzer. Filed dart-lang/sdk#34069 to see if we can avoid having to hack around lints in generated code like this.

[zoechi]

I also prefer configuring the analyzer, but because that dodn't work, using the header was a convemient workaround.

[davidmarne]

Alternatively, built_value or any other code generator could still support lints via the build_config. Instead of passing those into source_gen's builder like built_value did here built_value could pass it to it's generator

[kevmoo]

This is blocking google/json_serializable.dart#557

[natebosch]

This should not be blocking. I think you can drop an // ignore: anywhere in the file and it's fine to repeat it. It might not be pretty, but I wouldn't say it's blocking.

[kevmoo]

Really annoying?