codama-renderers-dart 0.5.0 → 0.5.3

package/src/fragments/instructionPage.ts

@@ -7,16 +7,20 @@ import { visit } from "@codama/visitors-core";
 
 import type { Fragment } from "../utils/fragment.js";
 import {
-  emptyFragment,
   fragment,
   fragmentFromString,
   mergeFragments,
   use,
 } from "../utils/fragment.js";
 import type { RenderScope } from "../utils/options.js";
-import { camelCase, pascalCase } from "../utils/nameTransformers.js";
+import { camelCase } from "../utils/nameTransformers.js";
+import { getDiscriminatorValidationFragment } from "../utils/discriminators.js";
+import { getTopLevelDecoderFragment } from "../utils/exactDecoder.js";
+import {
+  getDartValueFragment,
+  isConstDartValueNode,
+} from "../utils/valueNodes.js";
 import { getDiscriminatorConstantsFragment } from "./discriminatorConstants.js";
-import { WELL_KNOWN_ADDRESSES } from "../utils/wellKnownAddresses.js";
 
 /**
  * Generate a full Dart file for an instruction.
@@ -31,19 +35,55 @@ export function getInstructionPageFragment(
   const parseFnName = scope.nameApi.instructionParseFunction(name);
 
   const accounts = node.accounts ?? [];
-  const args = (node.arguments ?? []).filter(
-    (arg) => !isDiscriminatorArg(arg, node),
-  );
   const allArgs = node.arguments ?? [];
+  const optionalAccountStrategy: string =
+    node.optionalAccountStrategy ?? "programId";
+  if (
+    optionalAccountStrategy !== "programId" &&
+    optionalAccountStrategy !== "omitted"
+  ) {
+    throw new Error(
+      `Unsupported optional account strategy on instruction "${node.name}": ${optionalAccountStrategy}`,
+    );
+  }
+  const args = allArgs.filter(
+    (arg) =>
+      !isDiscriminatorArg(arg, node) && !isOmittedDefaultArgument(arg),
+  );
 
   // Build the instruction data class
   const dataClassName = `${typeName}InstructionData`;
 
   // Visit each arg type once and collect manifests for reuse
-  const allArgManifests = allArgs.map((arg) => ({
+  const allArgManifests = (node.arguments ?? []).map((arg) => ({
     arg,
     manifest: visit(arg.type, scope.typeManifestVisitor),
   }));
+  const argDefaultValues = new Map(
+    allArgManifests.flatMap(({ arg, manifest }) => {
+      if (arg.defaultValue == null) return [];
+      const needsRenderedDefault =
+        isOmittedDefaultArgument(arg) ||
+        isDiscriminatorArg(arg, node) ||
+        arg.defaultValue.kind !== "accountBumpValueNode";
+      if (!needsRenderedDefault) return [];
+      return [
+        [
+          arg,
+          getDartValueFragment(arg.defaultValue, manifest.type.content),
+        ] as const,
+      ];
+    }),
+  );
+  for (const arg of allArgs.filter((candidate) =>
+    isDiscriminatorArg(candidate, node),
+  )) {
+    if (!argDefaultValues.has(arg)) {
+      throw new Error(
+        `Field discriminator "${arg.name}" on instruction "${node.name}" must reference a field with a default value.`,
+      );
+    }
+  }
 
   // Data fields (non-discriminator arguments)
   const dataFieldDecls = allArgManifests
@@ -56,20 +96,25 @@ export function getInstructionPageFragment(
   const dataCtorParams = allArgManifests
     .map(({ arg, manifest }) => {
       const fieldName = camelCase(arg.name as string);
+      if (isOmittedDefaultArgument(arg)) return "";
       if (isDiscriminatorArg(arg, node)) {
         return isConstDefaultValue(arg.defaultValue)
-          ? `    this.${fieldName} = ${getDiscriminatorDefault(arg, node)},`
+          ? `    this.${fieldName} = ${argDefaultValues.get(arg)!.content},`
           : `    ${manifest.type.content}? ${fieldName},`;
       }
       return `    required this.${fieldName},`;
     })
+    .filter(Boolean)
     .join("\n");
 
   const dataCtorInitializers = allArgManifests
     .map(({ arg }) => {
       const fieldName = camelCase(arg.name as string);
+      if (isOmittedDefaultArgument(arg)) {
+        return `      ${fieldName} = ${argDefaultValues.get(arg)!.content}`;
+      }
       if (isDiscriminatorArg(arg, node) && !isConstDefaultValue(arg.defaultValue)) {
-        return `      ${fieldName} = ${fieldName} ?? ${getDiscriminatorDefault(arg, node)}`;
+        return `      ${fieldName} = ${fieldName} ?? ${argDefaultValues.get(arg)!.content}`;
       }
       return null;
     })
@@ -90,13 +135,17 @@ export function getInstructionPageFragment(
     .join("\n");
 
   const toMapFields = allArgs
-    .map(
-      (arg) =>
-        `      '${arg.name as string}': value.${camelCase(arg.name as string)},`,
-    )
+    .map((arg) => {
+      const value =
+        isOmittedDefaultArgument(arg) || isDiscriminatorArg(arg, node)
+          ? argDefaultValues.get(arg)!.content
+          : `value.${camelCase(arg.name as string)}`;
+      return `      '${arg.name as string}': ${value},`;
+    })
     .join("\n");
 
   const fromMapFields = allArgManifests
+    .filter(({ arg }) => !isOmittedDefaultArgument(arg))
     .map(({ arg, manifest }) => {
       const typeStr = manifest.type.content;
       const isNullable = typeStr.endsWith("?");
@@ -105,7 +154,20 @@ export function getInstructionPageFragment(
     })
     .join("\n");
 
-  const dataCtorKeyword = dataCtorInitializers ? "" : "const ";
+  const dataCtorKeyword = allArgs.every(
+    (arg) =>
+      !isOmittedDefaultArgument(arg) ||
+      isConstDartValueNode(arg.defaultValue!),
+  ) && allArgs.every(
+    (arg) =>
+      !isDiscriminatorArg(arg, node) ||
+      isConstDefaultValue(arg.defaultValue),
+  )
+    ? "const "
+    : "";
+  const dataCtorSignature = dataCtorParams
+    ? `${dataCtorKeyword}${dataClassName}({\n${dataCtorParams}\n  })${dataCtorInitializers ? ` :\n${dataCtorInitializers}` : ""};`
+    : `${dataCtorKeyword}${dataClassName}()${dataCtorInitializers ? ` :\n${dataCtorInitializers}` : ""};`;
   const dataEncoderName = `get${typeName}InstructionDataEncoder`;
   const dataDecoderName = `get${typeName}InstructionDataDecoder`;
   const dataCodecName = `get${typeName}InstructionDataCodec`;
@@ -116,6 +178,13 @@ export function getInstructionPageFragment(
   const hasProgramAddressCollision = argNames.has('programAddress') || accountNames.has('programAddress');
   const instrProgramParam = hasProgramAddressCollision ? 'instructionProgramAddress' : 'programAddress';
 
+  // The generated local holding the constructed instruction data must not
+  // collide with an account or argument parameter name.
+  let instructionDataLocal = 'instructionData';
+  while (argNames.has(instructionDataLocal) || accountNames.has(instructionDataLocal)) {
+    instructionDataLocal = `${instructionDataLocal}_`;
+  }
+
   // Build the instruction builder function
   const accountParams = accounts
     .map((acc) => {
@@ -155,7 +224,10 @@ export function getInstructionPageFragment(
       const role = getAccountRole(acc);
       const isOptional = acc.isOptional ?? false;
       if (isOptional) {
-        return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}),`;
+        if (optionalAccountStrategy === "omitted") {
+          return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}),`;
+        }
+        return `    if (${fieldName} != null) AccountMeta(address: ${fieldName}, role: ${role}) else AccountMeta(address: ${instrProgramParam}, role: AccountRole.readonly),`;
       }
       return `    AccountMeta(address: ${fieldName}, role: ${role}),`;
     })
@@ -165,19 +237,31 @@ export function getInstructionPageFragment(
   const dataConstruction = allArgs
     .map((arg) => {
       const fieldName = camelCase(arg.name as string);
-      if (isDiscriminatorArg(arg, node)) {
+      if (
+        isOmittedDefaultArgument(arg) ||
+        isDiscriminatorArg(arg, node)
+      ) {
         return ""; // Use default
       }
-      // Use 'arg_<name>' prefix to reference builder params without shadowing.
-      const typeStr2 = argManifestMap.get(arg)?.type.content;
       const skipDefault = arg.defaultValue?.kind === "accountBumpValueNode";
-      return `      ${fieldName}: ${fieldName}${arg.defaultValue != null && !skipDefault ? ` ?? ${getDefaultValue(arg, typeStr2)}` : ""},`;
+      return `      ${fieldName}: ${fieldName}${arg.defaultValue != null && !skipDefault ? ` ?? ${argDefaultValues.get(arg)!.content}` : ""},`;
     })
     .filter(Boolean)
     .join("\n");
 
   // Discriminator
   const discFragment = getDiscriminatorConstantsFragment(node, scope);
+  const discriminatorValidation = getDiscriminatorValidationFragment(
+    node,
+    scope,
+  );
+  const topLevelDecoder = getTopLevelDecoderFragment({
+    typeName: dataClassName,
+    description: `${name} instruction decoder`,
+    discriminatorValidation,
+    fromMapFields,
+    requireExactConsumption: true,
+  });
 
   const parts: Fragment[] = [
     fragment`// Auto-generated. Do not edit.
@@ -205,9 +289,7 @@ ${use("AccountRole", "solanaInstructions")}`,
   parts.push(fragment`
 @immutable
 class ${fragmentFromString(dataClassName)} {
-  ${fragmentFromString(dataCtorKeyword)}${fragmentFromString(dataClassName)}({
-${fragmentFromString(dataCtorParams)}
-  })${fragmentFromString(dataCtorInitializers ? ` :\n${dataCtorInitializers}` : "")};
+  ${fragmentFromString(dataCtorSignature)}
 
 ${fragmentFromString(dataFieldDecls)}
 }`);
@@ -232,12 +314,7 @@ Decoder<${fragmentFromString(dataClassName)}> ${fragmentFromString(dataDecoderNa
 ${fragmentFromString(decFields)}
   ]);
 
-  return transformDecoder(
-    structDecoder,
-    (Map<String, Object?> map, Uint8List bytes, int offset) => ${fragmentFromString(dataClassName)}(
-${fragmentFromString(fromMapFields)}
-    ),
-  );
+${topLevelDecoder}
 }
 
 Codec<${fragmentFromString(dataClassName)}, ${fragmentFromString(dataClassName)}> ${fragmentFromString(dataCodecName)}() {
@@ -252,7 +329,7 @@ Instruction ${fragmentFromString(instrFnName)}({
 ${fragmentFromString(accountParams)}
 ${fragmentFromString(argParams)}
 }) {
-  final instructionData = ${fragmentFromString(dataClassName)}(
+  final ${instructionDataLocal} = ${fragmentFromString(dataClassName)}(
 ${fragmentFromString(dataConstruction)}
   );
 
@@ -261,7 +338,7 @@ ${fragmentFromString(dataConstruction)}
     accounts: [
 ${fragmentFromString(accountMetas)}
     ],
-    data: ${fragmentFromString(dataEncoderName)}().encode(instructionData),
+    data: ${fragmentFromString(dataEncoderName)}().encode(${instructionDataLocal}),
   );
 }`);
 
@@ -280,6 +357,9 @@ ${fragmentFromString(dataClassName)} ${fragmentFromString(parseFnName)}(Instruct
     result.imports.mergeWith(manifest.decoder.imports);
     result.imports.mergeWith(manifest.type.imports);
   }
+  for (const defaultValue of argDefaultValues.values()) {
+    result.imports.mergeWith(defaultValue.imports);
+  }
 
   return result;
 }
@@ -305,23 +385,6 @@ function isDiscriminatorArg(
   );
 }
 
-function getDiscriminatorDefault(
-  arg: InstructionArgumentNode,
-  _node: InstructionNode,
-): string {
-  if (arg.defaultValue) {
-    if (arg.defaultValue.kind === "numberValueNode") {
-      return String(arg.defaultValue.number);
-    }
-    if (arg.defaultValue.kind === "bytesValueNode") {
-      const data = arg.defaultValue.data as string;
-      const bytes = data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
-      return `Uint8List.fromList([${bytes.join(", ")}])`;
-    }
-  }
-  return "0";
-}
-
 function isConstDefaultValue(defaultValue: InstructionArgumentNode["defaultValue"]): boolean {
   if (!defaultValue) return false;
   switch (defaultValue.kind) {
@@ -335,36 +398,6 @@ function isConstDefaultValue(defaultValue: InstructionArgumentNode["defaultValue
   }
 }
 
-function getDefaultValue(
-  arg: InstructionArgumentNode,
-  typeStr?: string,
-): string {
-  if (!arg.defaultValue) return "null";
-  const isBigInt = typeStr === "BigInt";
-  const dv = arg.defaultValue;
-  switch (dv.kind) {
-    case "numberValueNode":
-      // Dart's `BigInt` requires a constructor; `0` is not assignable to `BigInt`.
-      return isBigInt ? `BigInt.from(${dv.number})` : String(dv.number);
-    case "booleanValueNode":
-      return String(dv.boolean);
-    case "stringValueNode":
-      return `'${dv.string}'`;
-    case "publicKeyValueNode": {
-      const wellKnownName = WELL_KNOWN_ADDRESSES.get(dv.publicKey);
-      if (wellKnownName) {
-        use(wellKnownName, "solanaAddresses");
-        return wellKnownName;
-      }
-      return `Address('${dv.publicKey}')`;
-    }
-    case "noneValueNode":
-      return "null";
-    case "bytesValueNode": {
-      const bytes = dv.data.match(/.{1,2}/g)?.map((b) => parseInt(b, 16)) ?? [];
-      return `Uint8List.fromList([${bytes.join(", ")}])`;
-    }
-    default:
-      return "null";
-  }
+function isOmittedDefaultArgument(arg: InstructionArgumentNode): boolean {
+  return arg.defaultValue != null && arg.defaultValueStrategy === "omitted";
 }

package/src/fragments/typePage.ts

@@ -1,4 +1,9 @@
-import type { DefinedTypeNode, StructFieldTypeNode, TypeNode } from "@codama/nodes";
+import type {
+  DefinedTypeNode,
+  EnumVariantTypeNode,
+  StructFieldTypeNode,
+  TypeNode,
+} from "@codama/nodes";
 import { resolveNestedTypeNode } from "@codama/nodes";
 import { visit } from "@codama/visitors-core";
 
@@ -30,13 +35,14 @@ export function getTypePageFragment(
 
   // Check what kind of type this is
   if (typeNode.kind === "enumTypeNode") {
-    const isScalar = typeNode.variants.every(
+    const variants = typeNode.variants ?? [];
+    const isScalar = variants.every(
       (v) => v.kind === "enumEmptyVariantTypeNode",
     );
     if (isScalar) {
-      return getScalarEnumPageFragment(node, scope);
+      return getScalarEnumPageFragment(node, variants, scope);
     }
-    return getDataEnumPageFragment(node, scope);
+    return getDataEnumPageFragment(node, variants, scope);
   }
 
   if (typeNode.kind === "structTypeNode") {
@@ -52,6 +58,7 @@ export function getTypePageFragment(
  */
 function getScalarEnumPageFragment(
   node: DefinedTypeNode,
+  enumVariants: EnumVariantTypeNode[],
   scope: RenderScope,
 ): Fragment {
   const name = node.name as string;
@@ -59,7 +66,7 @@ function getScalarEnumPageFragment(
   const enumNode = node.type;
   if (enumNode.kind !== "enumTypeNode") return emptyFragment();
 
-  const variants = enumNode.variants.map((v) => {
+  const variants = enumVariants.map((v) => {
     const variantName = scope.nameApi.enumVariant(v.name as string);
     return variantName;
   });
@@ -73,6 +80,18 @@ function getScalarEnumPageFragment(
   const resolvedSize = resolveNestedTypeNode(enumNode.size);
   const sizeType = resolvedSize.format ?? "u8";
   const sizeCodecName = getNumberCodecName(sizeType);
+  const isU64 = sizeType === "u64";
+  const encodedVariantIndex = isU64
+    ? "BigInt.from(value.index)"
+    : "value.index";
+  const decodedVariant = isU64
+    ? `(BigInt value, Uint8List bytes, int offset) {
+      if (value.isNegative || value >= BigInt.from(${typeName}.values.length)) {
+        throw RangeError('Invalid ${typeName} discriminator: ' + value.toString());
+      }
+      return ${typeName}.values[value.toInt()];
+    }`
+    : `(int value, Uint8List bytes, int offset) => ${typeName}.values[value]`;
 
   return fragment`// Auto-generated. Do not edit.
 // ignore_for_file: type=lint
@@ -94,14 +113,14 @@ ${fragmentFromString(variantLines)}
 Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
   return transformEncoder(
     get${fragmentFromString(sizeCodecName)}Encoder(),
-    (${fragmentFromString(typeName)} value) => value.index,
+    (${fragmentFromString(typeName)} value) => ${fragmentFromString(encodedVariantIndex)},
   );
 }
 
 Decoder<${fragmentFromString(typeName)}> ${fragmentFromString(decoderName)}() {
   return transformDecoder(
     get${fragmentFromString(sizeCodecName)}Decoder(),
-    (int value, Uint8List bytes, int offset) => ${fragmentFromString(typeName)}.values[value],
+    ${fragmentFromString(decodedVariant)},
   );
 }
 
@@ -115,6 +134,7 @@ Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragme
  */
 function getDataEnumPageFragment(
   node: DefinedTypeNode,
+  variants: EnumVariantTypeNode[],
   scope: RenderScope,
 ): Fragment {
   const name = node.name as string;
@@ -127,11 +147,12 @@ function getDataEnumPageFragment(
   const decoderVariants: string[] = [];
   const encodeCases: string[] = [];
   const decodeCases: string[] = [];
+  let pageHasListEnums = false;
   // Collect all field type manifests from variants so we can merge their imports
   const allVariantManifests: { encoder: Fragment; decoder: Fragment; type: Fragment }[] = [];
 
-  for (let i = 0; i < enumNode.variants.length; i++) {
-    const variant = enumNode.variants[i];
+  for (let i = 0; i < variants.length; i++) {
+    const variant = variants[i];
     const variantName = pascalCase(variant.name as string);
     const variantClassName = scope.nameApi.sealedClassVariant(
       name,
@@ -163,7 +184,7 @@ function getDataEnumPageFragment(
       decodeCases.push(`case ${i}: return const ${variantClassName}();`);
     } else if (variant.kind === "enumStructVariantTypeNode") {
       const resolvedStruct = resolveNestedTypeNode(variant.struct);
-      const fields = resolvedStruct.fields;
+      const fields = resolvedStruct.fields ?? [];
 
       // Visit each field type once and collect manifests
       const fieldManifests = fields.map((f: StructFieldTypeNode) => ({
@@ -192,12 +213,18 @@ function getDataEnumPageFragment(
         fields.length === 0
           ? "true"
           : fields
-              .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)} == other.${camelCase(f.name as string)}`)
+              .map((f: StructFieldTypeNode, index) => {
+                const fieldName = camelCase(f.name as string);
+                return isListManifest(fieldManifests[index].manifest)
+                  ? `_listEquals(${fieldName}, other.${fieldName})`
+                  : `${fieldName} == other.${fieldName}`;
+              })
               .join(" &&\n          ");
 
-      const hashExpression = getHashExpression(
-        fields.map((f: StructFieldTypeNode) => camelCase(f.name as string)),
-      );
+      const hashExpression = getValueHashExpression(fields, fieldManifests);
+      if (fieldManifests.some(({ manifest }) => isListManifest(manifest))) {
+        pageHasListEnums = true;
+      }
 
       const toStringFields = fields
         .map((f: StructFieldTypeNode) => `${camelCase(f.name as string)}: $${camelCase(f.name as string)}`)
@@ -271,7 +298,7 @@ ${fieldDecls}
       decodeCases.push(`case ${i}: return ${variantClassName}(${fromMapFields.replace(/\n/g, ' ').replace(/,$/, '')});`);
     } else if (variant.kind === "enumTupleVariantTypeNode") {
       const resolvedTuple = resolveNestedTypeNode(variant.tuple);
-      const items = resolvedTuple.items;
+      const items = resolvedTuple.items ?? [];
       if (items.length === 1) {
         const manifest = visit(items[0], scope.typeManifestVisitor);
         allVariantManifests.push(manifest);
@@ -331,7 +358,7 @@ sealed class ${fragmentFromString(typeName)} {
   const ${fragmentFromString(typeName)}();
 }
 
-${fragmentFromString(variantClasses.join("\n\n"))}
+${fragmentFromString(variantClasses.join("\n\n"))}${pageHasListEnums ? LIST_VALUE_HELPERS : ""}
 
 Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
   return transformEncoder<Map<String, Object?>, ${fragmentFromString(typeName)}>(
@@ -384,7 +411,8 @@ function getStructPageFragment(
   const structNode = node.type;
   if (structNode.kind !== "structTypeNode") return emptyFragment();
 
-  const fields = structNode.fields;
+  const fields = structNode.fields ?? [];
+  let pageHasListStructs = false;
 
   // Visit each field type once and collect manifests for reuse
   const fieldManifests = fields.map((f: StructFieldTypeNode) => ({
@@ -409,19 +437,17 @@ function getStructPageFragment(
   const eqChecks =
     fields.length === 0
       ? "true"
-      : fields
-          .map(
-            (f: StructFieldTypeNode) =>
-              `${camelCase(f.name as string)} == other.${camelCase(f.name as string)}`,
-          )
+      : fieldManifests
+          .map(({ field: f, manifest }, index) => {
+            const fieldName = camelCase(f.name as string);
+            return isListManifest(manifest)
+              ? `_listEquals(${fieldName}, other.${fieldName})`
+              : `${fieldName} == other.${fieldName}`;
+          })
           .join(" &&\n          ");
-
-  const hashFields =
-    fields.length === 0
-      ? "runtimeType"
-      : fields
-          .map((f: StructFieldTypeNode) => camelCase(f.name as string))
-          .join(", ");
+  if (fieldManifests.some(({ manifest }) => isListManifest(manifest))) {
+    pageHasListStructs = true;
+  }
 
   const toStringFields = fields
     .map(
@@ -491,12 +517,14 @@ ${fragmentFromString(fieldDecls)}
           ${fragmentFromString(eqChecks)};
 
   @override
-  int get hashCode => ${fragmentFromString(getHashExpression(fields.map((f: StructFieldTypeNode) => camelCase(f.name as string))))};
+  int get hashCode => ${fragmentFromString(
+    getValueHashExpression(fields, fieldManifests),
+  )};
 
   @override
   String toString() => '${fragmentFromString(typeName)}(${fragmentFromString(toStringFields)})';
 }
-
+${pageHasListStructs ? LIST_VALUE_HELPERS : ""}
 Encoder<${fragmentFromString(typeName)}> ${fragmentFromString(encoderName)}() {
   final structEncoder = getStructEncoder(<(String, Encoder<Object?>)>[
 ${fragmentFromString(encFields)}
@@ -575,6 +603,81 @@ Codec<${fragmentFromString(typeName)}, ${fragmentFromString(typeName)}> ${fragme
 }`;
 }
 
+/**
+ * Returns true when the rendered field type is a Dart list or byte sequence,
+ * whose reference equality must be replaced with a deep comparison in
+ * generated value classes.
+ */
+function isListManifest(manifest: { type: Fragment }): boolean {
+  return manifest.type.content.startsWith("List<") ||
+    manifest.type.content === "Uint8List";
+}
+
+/**
+ * Private Dart helpers emitted into pages whose value classes contain
+ * list-typed fields, so `==` and `hashCode` match recursive structural value
+ * equality instead of list reference identity. The recursive branch matters
+ * for generated types such as `List<Uint8List>`.
+ */
+const LIST_VALUE_HELPERS = `
+bool _listEquals<T>(List<T>? a, List<T>? b) {
+  if (identical(a, b)) return true;
+  if (a == null || b == null) return a == b;
+  if (a.length != b.length) return false;
+  for (var i = 0; i < a.length; i++) {
+    final left = a[i];
+    final right = b[i];
+    if (left is List<Object?> && right is List<Object?>) {
+      if (!_listEquals(left, right)) return false;
+    } else if (left != right) {
+      return false;
+    }
+  }
+  return true;
+}
+
+Object? _deepHash(Object? value) {
+  if (value is List<Object?>) {
+    return Object.hashAll(value.map(_deepHash));
+  }
+  return value;
+}
+
+int _listHashCode<T>(List<T>? a) {
+  if (a == null) return 0;
+  return Object.hashAll(a.map(_deepHash));
+}
+`;
+
+/**
+ * Builds the `hashCode` expression for a class whose fields render as the
+ * given lowercase names. List-typed fields compare structurally through the
+ * private `_listHashCode` helper emitted alongside the class.
+ */
+function getValueHashExpression(
+  fields: StructFieldTypeNode[],
+  fieldManifests: { field: StructFieldTypeNode; manifest: { type: Fragment } }[],
+): string {
+  const fieldNames = fields.map((f: StructFieldTypeNode) =>
+    camelCase(f.name as string),
+  );
+  const hasListFields = fieldManifests.some(({ manifest }) =>
+    isListManifest(manifest),
+  );
+  if (!hasListFields) {
+    return getHashExpression(fieldNames);
+  }
+  if (fieldNames.length === 1) {
+    return `_listHashCode(${fieldNames[0]})`;
+  }
+  const hashArgs = fields.map((f: StructFieldTypeNode, index) =>
+    isListManifest(fieldManifests[index].manifest)
+      ? `_listHashCode(${camelCase(f.name as string)})`
+      : camelCase(f.name as string),
+  );
+  return `Object.hash(${hashArgs.join(", ")})`;
+}
+
 function getHashExpression(fields: string[]): string {
   if (fields.length === 0) return "runtimeType.hashCode";
   if (fields.length === 1) return `${fields[0]}.hashCode`;

package/src/index.ts

@@ -3,6 +3,7 @@ export { getRenderMapVisitor } from "./visitors/getRenderMapVisitor.js";
 export { getTypeManifestVisitor } from "./visitors/getTypeManifestVisitor.js";
 export { DartImportMap, DART_EXTERNAL_PACKAGE_MAP } from "./utils/importMap.js";
 export { createDartNameApi } from "./utils/nameTransformers.js";
+export { normalizeRootNode } from "./utils/normalizeRootNode.js";
 export type { DartNameApi } from "./utils/nameTransformers.js";
 export type { RenderOptions, GetRenderMapOptions, RenderScope } from "./utils/options.js";
 export type { TypeManifest } from "./utils/typeManifest.js";