Add package:checks_codegen

[natebosch]

Initial open sourcing of the code generation companion to
package:checks. This generates extension using the .has() utility
for each field in the classes specified for generation.

Add an annotation to mark imports of the generated libraries as a
trigger for the codegen as configuration for which types to generate
for. Add the builder using package:source_gen to target the
annotation. Add tests using package:build_test. Add an example with a
checked in generated file.

[github-actions]

PR Health

Changelog Entry ✔️

Package	Changed Files

Changes to files need to be accounted for in their respective changelogs.

This check can be disabled by tagging the PR with skip-changelog-check.

[github-actions]

Package publishing

Package	Version	Status	Publish tag (post-merge)
package:checks	0.3.2-wip	WIP (no publish necessary)
package:checks_codegen	0.1.0	ready to publish	checks_codegen-v0.1.0
package:fake_async	1.3.3	already published at pub.dev
package:matcher	0.12.20	already published at pub.dev
package:test	1.31.2-wip	WIP (no publish necessary)
package:test_api	0.7.13-wip	WIP (no publish necessary)
package:test_core	0.6.19-wip	WIP (no publish necessary)
package:test_descriptor	2.0.2	already published at pub.dev
package:test_process	2.1.1	already published at pub.dev

Documentation at https://github.com/dart-lang/ecosystem/wiki/Publishing-automation.

[jonasfj]

I LOVE more generation support for checks.

I'm a little unsure if a foo_test.checks.dart file for each test file is desirable.

[jonasfj]

crazy idea: We could detect at code-gen time that there are no extensions for Subject<TypedData> and on the basis of this generate such an extension.

Probably there are some potential issues around what to do if there are extensions for a super type... and maybe it's a bit fragile.

But it would be cool, to do in a future where users commonly have dart run build_runner watch sitting in the background, then you'd just write checks(foo) and it'd magically work on demand.

Do ignore this comment, because, yes I can see lots of reasons not to be this magical 🤣

[natebosch]

I think I like the idea of generating for all definitions of imported libraries a bit more than I like parsing test bodies to detect which types are used.

[jonasfj]

Suggested change

	/// Annotate an import to the `.checks.dart` library.
	/// Annotate an import to the `.checks.dart` library.
	///
	/// {@example /example/test/example_test.dart}

[natebosch]

I don't see @example listed at https://github.com/dart-lang/dartdoc/blob/main/doc/directives.md

Is there support for custom doc directives with @example defined somewhere?

[jonasfj]

I think it might not have been documented, I'll ask..

[jonasfj]

This limitation should probably be documented on CheckExtensions.

---

Orthogonal question: is this a good idea? Is it not a bit excessive to have a <name>_test.checks.dart file for each <name>_test.dart file?

I'll grant that I'm not 100% sure how to otherwise do it.

In my projects so far I've often done a test/checks_ext.dart file and then I write all the checks extensions I need/want into that file.

Often times I also end up making a test/harness.dart which exports checks extensions and one or more wrappers for test(), like testWithContext(String name, FutureOr<void> Function(Context ctx) fn) for some Context.

---

We could also have test/my_checks_stuff.dart like:

@CheckExtensions()
library;

import 'dart:io';
import 'dart:typed_data';

// Then just generate Subject<T> extensions for all classes T that are
// imported in this library, into the part file below:
part 'my_checks_stuff.g.dart';

This would:

• Give users a single library that contains all the checks extensions (granted with two part files)
• Avoid a library with checks extensions for each _test.dart file.
• Let users control if they want to limit how much is generated using show/hide modifiers.
• Let users write import '...' and export '...', so that their tests just imports test/my_checks_stuff.dart and nothing else.
• Give users a place to put their manually written checks extensions, and a natural place to write test helpers.
• Stick to the common <name>.g.dart pattern for generated files.

Granted there is a serious risk that people will import too much and generate HUGE part files. So it might make sense to keep the @CheckExtensions([TypeData, ...]) annotation. On the other hand, generating a lot of extensions is hopefully fairly harmless 🤣

[jonasfj]

nit:

Would be nice to use:

@Target(.importDirective)
class CheckExtensions {

But it doesn't exist :/

We could .directive but it's deprecated:
https://pub.dev/documentation/meta/latest/meta_meta/TargetKind/directive-constant.html

[jonasfj]

Consider using source span from element, it's not perfect, but better than nothing.

Makes more sense if using InvalidGenerationSource.

For package:typed_sql I ended up abandoning GeneratorForAnnotation inorder to make sure I could access the annotation source spans:

https://github.com/google/dart-neats/blob/7cb984e7d85b0201b5b110629afa45a9ed580adf/typed_sql/lib/src/codegen/analyzer_utils.dart

Granted, this is probably something we should put into package:source_gen at some point.

[jonasfj]

Probably, this is a user error? If I put a function type into the annotation:

typedef Foo = int Function(int);

@CheckExtensions([Foo])

Granted it's a corner case.

[natebosch]

I'm a little unsure if a foo_test.checks.dart file for each test file is desirable.

I'm unsure about generating for entire imported surface area, but I think we can also add that down the line if we make the argument to the annotation optional. I do think the shared test utility file is a pattern worth supporting, and it's pretty easy to do if we expand the targets for the annotation to exports as well. WDYT about the new example?

[jonasfj]

WDYT about the new example?

This is a great example!

I can see that there is really no need for a part-file, just generating a <basename>.checks.dart is perfectly fine.

And you're probably right to keep the <basename>.checks.dart constraint on the filename, because that means there is one canonical place where the @CheckExtensions annotation is made.

Even if people might import <basename>.checks.dart from other libraries (granted they probably shouldn't).

[jonasfj]

nit:

Suggested change

	throw InvalidGenerationSourceError(
	'must annotate an import or export of $expectedImport',
	);
	throw InvalidGenerationSourceError(
	'must annotate an import or export of $expectedImport',
	element: directive,
	);

I think that might work, and probably better than hanging it off nothing, not sure we can easily hang it off the annotation.

[natebosch]

The problem here is an ElementDirective isn't an Element. I didn't see a way to get a relevant Element instance in this code path.