[pub_formats] Make nullable params optional (#2459)

For the generated syntax inside `package:hooks`, `code_assets`, and `data_assets` all nullable parameters are `required`. This is to help us ensure that we don't forget a param in the semantic API. (The generated syntax is wrapped with an API handcrafted to be nice for our users.)

However, in `package:pub_formats` we don't have a semantic API wrapping the syntax, we directly use the syntax classes in `dartdev` and friends. In such case it's unwanted to have to provide every param. (For example when constructing a `pubspec.yaml` we want to omit all the optional sections.)

So, we add a param to the generator to control this.

Author: dcharkes

pkgs/hooks/tool/generate_syntax.dart

@@ -90,6 +90,7 @@ void main(List<String> args) {
 
     final output = SyntaxGenerator(
       analyzedSchema,
+      requireNullableParameters: true,
       header:
           '''
 // This file is generated, do not edit.

pkgs/json_syntax_generator/lib/src/generator/normal_class_generator.dart

@@ -9,7 +9,13 @@ import 'property_generator.dart';
 class ClassGenerator {
   final NormalClassInfo classInfo;
 
-  ClassGenerator(this.classInfo);
+  /// If true, also generate `required` named parameters for nullable fields.
+  ///
+  /// This is useful for ensuring that all fields are set when writing a
+  /// semantic Dart API that wraps a generated syntax.
+  final bool requireNullableParameters;
+
+  ClassGenerator(this.classInfo, {required this.requireNullableParameters});
 
   String generate() {
     final buffer = StringBuffer();
@@ -143,6 +149,11 @@ static const ${tagProperty}Value = '$tagValue';
     for (final propertyName in propertyNames) {
       final superClassProperty = superclass?.getProperty(propertyName);
       final thisClassProperty = classInfo.getProperty(propertyName);
+      final required =
+          !(thisClassProperty ?? superClassProperty)!.type.isNullable ||
+              requireNullableParameters
+          ? 'required'
+          : '';
 
       if (superClassProperty != null) {
         if (propertyName != classInfo.superclass?.taggedUnionProperty) {
@@ -152,17 +163,17 @@ static const ${tagProperty}Value = '$tagValue';
             // Must be passed to super constructor call.
             final dartType = thisClassProperty.type;
             final propertyName = thisClassProperty.name;
-            result.add('required $dartType $propertyName');
+            result.add('$required $dartType $propertyName');
           } else {
             // Same type on this class, emit super parameter.
             final propertyName = superClassProperty.name;
-            result.add('required super.$propertyName');
+            result.add('$required super.$propertyName');
           }
         }
       } else {
         final dartType = thisClassProperty!.type;
         final propertyName = thisClassProperty.name;
-        result.add('required $dartType $propertyName');
+        result.add('$required $dartType $propertyName');
       }
     }
     result.add('super.path = const []');

pkgs/json_syntax_generator/lib/src/generator/syntax_generator.dart

@@ -12,9 +12,21 @@ import 'normal_class_generator.dart';
 class SyntaxGenerator {
   final SchemaInfo schemaInfo;
 
+  /// If `true`, also generate `required` named parameters for nullable fields.
+  ///
+  /// This is useful for ensuring that all fields are set when writing a
+  /// semantic Dart API that wraps a generated syntax.
+  ///
+  /// If the generated syntax is used directly, prefer `false`.
+  final bool requireNullableParameters;
+
   final String header;
 
-  SyntaxGenerator(this.schemaInfo, {this.header = ''});
+  SyntaxGenerator(
+    this.schemaInfo, {
+    this.header = '',
+    this.requireNullableParameters = false,
+  });
 
   String generate() {
     final buffer = StringBuffer();
@@ -34,7 +46,12 @@ import 'dart:io';
     for (final classInfo in schemaInfo.classes) {
       switch (classInfo) {
         case NormalClassInfo():
-          buffer.writeln(ClassGenerator(classInfo).generate());
+          buffer.writeln(
+            ClassGenerator(
+              classInfo,
+              requireNullableParameters: requireNullableParameters,
+            ).generate(),
+          );
         case EnumClassInfo():
           buffer.writeln(EnumGenerator(classInfo).generate());
       }

pkgs/pub_formats/lib/src/package_graph_syntax.g.dart

@@ -16,7 +16,7 @@ class GraphPackageSyntax extends JsonObjectSyntax {
 
   GraphPackageSyntax({
     required List<String> dependencies,
-    required List<String>? devDependencies,
+    List<String>? devDependencies,
     required String name,
     required String version,
     super.path = const [],
@@ -90,7 +90,7 @@ class PackageGraphFileSyntax extends JsonObjectSyntax {
     : super.fromJson();
 
   PackageGraphFileSyntax({
-    required int? configVersion,
+    int? configVersion,
     required List<GraphPackageSyntax> packages,
     required List<String> roots,
     super.path = const [],

pkgs/pub_formats/lib/src/pubspec_lock_syntax.g.dart

@@ -407,7 +407,7 @@ class PubspecLockFileSyntax extends JsonObjectSyntax {
     : super.fromJson();
 
   PubspecLockFileSyntax({
-    required Map<String, PackageSyntax>? packages,
+    Map<String, PackageSyntax>? packages,
     required SDKsSyntax sdks,
     super.path = const [],
   }) : super() {

pkgs/pub_formats/lib/src/pubspec_syntax.g.dart

@@ -28,7 +28,7 @@ class EnvironmentSyntax extends JsonObjectSyntax {
     : super.fromJson();
 
   EnvironmentSyntax({
-    required String? flutter,
+    String? flutter,
     required String sdk,
     super.path = const [],
   }) : super() {
@@ -68,8 +68,8 @@ class GitSyntax extends JsonObjectSyntax {
   GitSyntax.fromJson(super.json, {super.path = const []}) : super.fromJson();
 
   GitSyntax({
-    required String? path$,
-    required String? ref,
+    String? path$,
+    String? ref,
     required String url,
     super.path = const [],
   }) : super() {
@@ -160,7 +160,7 @@ class HooksSyntax extends JsonObjectSyntax {
   HooksSyntax.fromJson(super.json, {super.path = const []}) : super.fromJson();
 
   HooksSyntax({
-    required Map<String, Map<String, Object?>>? userDefines,
+    Map<String, Map<String, Object?>>? userDefines,
     super.path = const [],
   }) : super() {
     _userDefines = userDefines;
@@ -198,7 +198,7 @@ class HostedDependencySourceSyntax extends DependencySourceSyntax {
     : super.fromJson();
 
   HostedDependencySourceSyntax({
-    required String? hosted,
+    String? hosted,
     required String version,
     super.path = const [],
   }) : super() {
@@ -279,20 +279,20 @@ class PubspecYamlFileSyntax extends JsonObjectSyntax {
     : super.fromJson();
 
   PubspecYamlFileSyntax({
-    required Map<String, DependencySourceSyntax>? dependencies,
-    required Map<String, DependencySourceSyntax>? dependencyOverrides,
-    required String? description,
-    required Map<String, DependencySourceSyntax>? devDependencies,
-    required String? documentation,
+    Map<String, DependencySourceSyntax>? dependencies,
+    Map<String, DependencySourceSyntax>? dependencyOverrides,
+    String? description,
+    Map<String, DependencySourceSyntax>? devDependencies,
+    String? documentation,
     required EnvironmentSyntax environment,
-    required Map<String, String?>? executables,
-    required String? homepage,
-    required HooksSyntax? hooks,
-    required String? issueTracker,
+    Map<String, String?>? executables,
+    String? homepage,
+    HooksSyntax? hooks,
+    String? issueTracker,
     required String name,
-    required String? publishTo,
-    required String? repository,
-    required String? version,
+    String? publishTo,
+    String? repository,
+    String? version,
     super.path = const [],
   }) : super() {
     this.dependencies = dependencies;