codama-renderers-dart 0.5.0 → 0.5.3

package/src/utils/discriminators.ts

@@ -0,0 +1,121 @@
+import type {
+  AccountNode,
+  ConstantValueNode,
+  InstructionNode,
+  StructFieldTypeNode,
+} from "@codama/nodes";
+import { resolveNestedTypeNode } from "@codama/nodes";
+import { visit } from "@codama/visitors-core";
+
+import type { Fragment } from "./fragment.js";
+import {
+  emptyFragment,
+  fragment,
+  fragmentFromString,
+  mergeFragments,
+  use,
+} from "./fragment.js";
+import type { RenderScope } from "./options.js";
+import { getDartValueFragment } from "./valueNodes.js";
+
+type DiscriminatedNode = AccountNode | InstructionNode;
+
+/**
+ * Generate decoder guards for every discriminator declared by a Codama node.
+ */
+export function getDiscriminatorValidationFragment(
+  node: DiscriminatedNode,
+  scope: RenderScope,
+): Fragment {
+  const discriminators = node.discriminators ?? [];
+  if (discriminators.length === 0) return emptyFragment();
+
+  const fields = getDiscriminatorFields(node);
+  const fragments = discriminators.map((discriminator): Fragment => {
+    switch (discriminator.kind) {
+      case "constantDiscriminatorNode":
+        return getConstantValidationFragment(
+          discriminator.constant,
+          discriminator.offset,
+          scope,
+        );
+      case "fieldDiscriminatorNode": {
+        const field = fields.find(
+          (candidate) => candidate.name === discriminator.name,
+        );
+        if (field?.defaultValue == null) {
+          throw new Error(
+            `Field discriminator "${discriminator.name}" on ${node.kind} "${node.name}" must reference a field with a default value.`,
+          );
+        }
+        return getConstantValidationFragment(
+          {
+            kind: "constantValueNode",
+            type: field.type,
+            value: field.defaultValue,
+          } as ConstantValueNode,
+          discriminator.offset,
+          scope,
+        );
+      }
+      case "sizeDiscriminatorNode": {
+        if (
+          !Number.isSafeInteger(discriminator.size) ||
+          discriminator.size < 0
+        ) {
+          throw new Error(
+            `Discriminator size must be a non-negative safe integer, got ${discriminator.size}.`,
+          );
+        }
+        return fragment`if (bytes.length - offset != ${fragmentFromString(String(discriminator.size))}) {
+  throw ${use("SolanaError", "solanaErrors")}(
+    ${use("SolanaErrorCode", "solanaErrors")}.codecsInvalidByteLength,
+    {
+      'codecDescription': '${fragmentFromString(node.name as string)} discriminator',
+      'expected': ${fragmentFromString(String(discriminator.size))},
+      'bytesLength': bytes.length - offset,
+    },
+  );
+}`;
+      }
+    }
+  });
+
+  return mergeFragments(fragments, (contents) => contents.join("\n"));
+}
+
+function getConstantValidationFragment(
+  constant: ConstantValueNode,
+  discriminatorOffset: number,
+  scope: RenderScope,
+): Fragment {
+  if (!Number.isSafeInteger(discriminatorOffset) || discriminatorOffset < 0) {
+    throw new Error(
+      `Discriminator offset must be a non-negative safe integer, got ${discriminatorOffset}.`,
+    );
+  }
+
+  const manifest = visit(constant.type, scope.typeManifestVisitor);
+  const value = getDartValueFragment(
+    constant.value,
+    manifest.type.content,
+  );
+  return fragment`${use("getConstantDecoder", "solanaCodecsDataStructures")}(
+  ${manifest.encoder}.encode(${value}),
+).read(bytes, offset + ${fragmentFromString(String(discriminatorOffset))});`;
+}
+
+function getDiscriminatorFields(
+  node: DiscriminatedNode,
+): readonly StructFieldTypeNode[] {
+  if (node.kind === "accountNode") {
+    return resolveNestedTypeNode(node.data).fields ?? [];
+  }
+  return (node.arguments ?? []).map(
+    (argument) =>
+      ({
+        ...argument,
+        kind: "structFieldTypeNode",
+      }) as StructFieldTypeNode,
+  );
+}

package/src/utils/exactDecoder.ts

@@ -0,0 +1,82 @@
+import type { Fragment } from "./fragment.js";
+import { fragment, fragmentFromString, use } from "./fragment.js";
+
+export interface TopLevelDecoderFragmentOptions {
+  readonly typeName: string;
+  readonly description: string;
+  readonly discriminatorValidation: Fragment;
+  readonly fromMapFields: string;
+  readonly requireExactConsumption: boolean;
+}
+
+/**
+ * Wrap a generated top-level struct decoder with discriminator and length
+ * validation.
+ *
+ * The wrapper preserves fixed/variable decoder metadata so it remains
+ * compatible with the matching generated encoder when combined into a codec.
+ */
+export function getTopLevelDecoderFragment({
+  typeName,
+  description,
+  discriminatorValidation,
+  fromMapFields,
+  requireExactConsumption,
+}: TopLevelDecoderFragmentOptions): Fragment {
+  const validation = discriminatorValidation.content
+    ? `    ${discriminatorValidation.content.replaceAll("\n", "\n    ")}\n`
+    : "";
+
+  const consumptionCheck = requireExactConsumption
+    ? `    if (newOffset != bytes.length) {
+      throwInvalidByteLength(newOffset - offset, bytes.length - offset);
+    }
+`
+    : "";
+  const fixedSizeCheck = requireExactConsumption
+    ? "bytesLength != structDecoder.fixedSize"
+    : "bytesLength < structDecoder.fixedSize";
+
+  const result = fragment`  Never throwInvalidByteLength(int expected, int bytesLength) {
+    throw ${use("SolanaError", "solanaErrors")}(
+      ${use("SolanaErrorCode", "solanaErrors")}.codecsInvalidByteLength,
+      {
+        'codecDescription': '${fragmentFromString(description)}',
+        'expected': expected,
+        'bytesLength': bytesLength,
+      },
+    );
+  }
+
+  (${fragmentFromString(typeName)}, int) readTopLevel(Uint8List bytes, int offset) {
+${fragmentFromString(validation)}    final (map, newOffset) = structDecoder.read(bytes, offset);
+${fragmentFromString(consumptionCheck)}
+    return (
+      ${fragmentFromString(typeName)}(
+${fragmentFromString(fromMapFields)}
+      ),
+      newOffset,
+    );
+  }
+
+  return switch (structDecoder) {
+    ${use("FixedSizeDecoder", "solanaCodecsCore")}<Map<String, Object?>>() =>
+      ${use("FixedSizeDecoder", "solanaCodecsCore")}<${fragmentFromString(typeName)}>(
+        fixedSize: structDecoder.fixedSize,
+        read: (bytes, offset) {
+          final bytesLength = bytes.length - offset;
+          if (${fragmentFromString(fixedSizeCheck)}) {
+            throwInvalidByteLength(structDecoder.fixedSize, bytesLength);
+          }
+          return readTopLevel(bytes, offset);
+        },
+      ),
+    ${use("VariableSizeDecoder", "solanaCodecsCore")}<Map<String, Object?>>() =>
+      ${use("VariableSizeDecoder", "solanaCodecsCore")}<${fragmentFromString(typeName)}>(
+        read: readTopLevel,
+        maxSize: structDecoder.maxSize,
+      ),
+  };`;
+  result.imports.mergeWith(discriminatorValidation.imports);
+  return result;
+}

package/src/utils/formatCode.ts

@@ -2,11 +2,11 @@ import { execSync } from "node:child_process";
 
 /**
  * Format Dart code using `dart format`.
- * Falls back to returning the unformatted code if dart is not available.
+ * Falls back to returning the unformatted code if Dart is not available.
  */
 export function formatDartCode(code: string): string {
   try {
-    const result = execSync("dart format --fix -", {
+    const result = execSync("dart format --output=show", {
       input: code,
       encoding: "utf-8",
       timeout: 30_000,
@@ -23,13 +23,9 @@ export function formatDartCode(code: string): string {
  * Format all Dart files in a directory using `dart format`.
  */
 export function formatDartDirectory(dir: string): void {
-  try {
-    execSync(`dart format --fix "${dir}"`, {
-      encoding: "utf-8",
-      timeout: 60_000,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-  } catch {
-    // Silently ignore if dart format is not available
-  }
+  execSync(`dart format "${dir}"`, {
+    encoding: "utf-8",
+    timeout: 60_000,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
 }

package/src/utils/index.ts

@@ -1,8 +1,12 @@
 export * from "./codecs.js";
+export * from "./discriminators.js";
+export * from "./exactDecoder.js";
 export * from "./formatCode.js";
 export * from "./fragment.js";
 export * from "./importMap.js";
 export * from "./nameTransformers.js";
+export * from "./normalizeRootNode.js";
 export * from "./options.js";
 export * from "./typeManifest.js";
+export * from "./valueNodes.js";
 export * from "./wellKnownAddresses.js";

package/src/utils/nameTransformers.ts

@@ -11,10 +11,37 @@ export function pascalCase(str: string): string {
     .replace(/^(.)/, (c) => c.toUpperCase());
 }
 
+/**
+ * Dart reserved words (plus `async`/`await`/`yield` where they cannot be
+ * plain identifiers). A lowercase declaration named with one of these must
+ * be escaped, e.g. an account named `null` becomes a `null_` parameter.
+ */
+const DART_RESERVED_WORDS = new Set([
+  "abstract", "as", "assert", "async", "augment", "await", "base",
+  "break", "case", "catch", "class", "const", "continue", "covariant",
+  "default", "deferred", "do", "dynamic", "else", "enum", "export",
+  "extends", "extension", "external", "factory", "false", "final",
+  "finally", "for", "get", "hide", "if", "implements", "import", "in",
+  "interface", "is", "late", "library", "mixin", "native", "new", "null",
+  "of", "on", "operator", "part", "required", "rethrow", "return",
+  "sealed", "set", "show", "static", "super", "switch", "sync", "this",
+  "throw", "true", "try", "typedef", "var", "void", "when", "while",
+  "with", "yield",
+]);
+
+/**
+ * Escape a lowercase identifier if it collides with a Dart reserved word
+ * by appending `_` (e.g. an account named `null` renders as `null_`).
+ */
+export function escapeDartIdentifier(name: string): string {
+  return DART_RESERVED_WORDS.has(name) ? `${name}_` : name;
+}
+
 /** Convert a string to camelCase */
 export function camelCase(str: string): string {
   const pascal = pascalCase(str);
-  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  const cased = pascal.charAt(0).toLowerCase() + pascal.slice(1);
+  return escapeDartIdentifier(cased);
 }
 
 /** Convert a string to snake_case */

package/src/utils/normalizeRootNode.ts

@@ -0,0 +1,76 @@
+import type { RootNode } from "@codama/nodes";
+
+/**
+ * Normalizes a serialized Codama root before it reaches Codama's visitors.
+ *
+ * Codama constructors materialize empty child collections, while generated
+ * JSON commonly omits them. Pina intentionally omits those empty fields, so
+ * restore only the structural defaults required by Codama traversal. This is
+ * a copy: callers retain their original parsed IDL unchanged.
+ */
+export function normalizeRootNode(root: RootNode): RootNode {
+  return normalizeNode(root) as RootNode;
+}
+
+function normalizeNode(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(normalizeNode);
+  }
+
+  if (!isRecord(value)) {
+    return value;
+  }
+
+  const normalized = Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [key, normalizeNode(child)]),
+  ) as Record<string, unknown>;
+
+  switch (normalized.kind) {
+    case "rootNode":
+      setEmptyCollection(normalized, "additionalPrograms");
+      break;
+    case "programNode":
+      setEmptyCollection(normalized, "accounts");
+      setEmptyCollection(normalized, "constants");
+      setEmptyCollection(normalized, "definedTypes");
+      setEmptyCollection(normalized, "errors");
+      setEmptyCollection(normalized, "events");
+      setEmptyCollection(normalized, "instructions");
+      setEmptyCollection(normalized, "pdas");
+      break;
+    case "instructionNode":
+      setEmptyCollection(normalized, "accounts");
+      setEmptyCollection(normalized, "arguments");
+      break;
+    case "pdaNode":
+      setEmptyCollection(normalized, "seeds");
+      break;
+    case "structTypeNode":
+      setEmptyCollection(normalized, "fields");
+      break;
+    case "enumTypeNode":
+      setEmptyCollection(normalized, "variants");
+      break;
+    case "tupleTypeNode":
+      setEmptyCollection(normalized, "items");
+      break;
+    case "hiddenPrefixTypeNode":
+      setEmptyCollection(normalized, "prefix");
+      break;
+    case "hiddenSuffixTypeNode":
+      setEmptyCollection(normalized, "suffix");
+      break;
+  }
+
+  return normalized;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function setEmptyCollection(record: Record<string, unknown>, key: string): void {
+  if (record[key] === undefined) {
+    record[key] = [];
+  }
+}

package/src/utils/valueNodes.ts

@@ -0,0 +1,87 @@
+import type {
+  InstructionInputValueNode,
+  ValueNode,
+} from "@codama/nodes";
+
+import type { Fragment } from "./fragment.js";
+import { fragment, fragmentFromString, use } from "./fragment.js";
+import { WELL_KNOWN_ADDRESSES } from "./wellKnownAddresses.js";
+
+type RenderableValueNode = InstructionInputValueNode | ValueNode;
+
+/**
+ * Render a standalone Codama value as a Dart expression.
+ *
+ * Contextual instruction values need resolver state and are deliberately
+ * rejected here. Defaults and discriminators must be deterministic at code
+ * generation time so generated encoders cannot silently choose a different
+ * wire value.
+ */
+export function getDartValueFragment(
+  value: RenderableValueNode,
+  dartType?: string,
+): Fragment {
+  switch (value.kind) {
+    case "numberValueNode":
+      return fragmentFromString(
+        dartType === "BigInt"
+          ? `BigInt.from(${value.number})`
+          : String(value.number),
+      );
+    case "booleanValueNode":
+      return fragmentFromString(String(value.boolean));
+    case "stringValueNode":
+      return fragmentFromString(toDartStringLiteral(value.string));
+    case "noneValueNode":
+      return fragmentFromString("null");
+    case "bytesValueNode": {
+      if (value.encoding !== "base16") {
+        throw new Error(
+          `Unsupported deterministic bytes encoding: ${value.encoding}`,
+        );
+      }
+      const clean = value.data.replace(/^0x/, "");
+      if (clean.length % 2 !== 0 || !/^[0-9a-f]*$/i.test(clean)) {
+        throw new Error(`Invalid hexadecimal bytes value: ${value.data}`);
+      }
+      const bytes = clean.match(/.{2}/g)?.map((byte) => `0x${byte}`) ?? [];
+      return fragment`${use("Uint8List", "dartTypedData")}.fromList([${fragmentFromString(bytes.join(", "))}])`;
+    }
+    case "publicKeyValueNode": {
+      const wellKnownName = WELL_KNOWN_ADDRESSES.get(value.publicKey);
+      return wellKnownName
+        ? fragment`${use(wellKnownName, "solanaAddresses")}`
+        : fragment`${use("Address", "solanaAddresses")}(${fragmentFromString(toDartStringLiteral(value.publicKey))})`;
+    }
+    default:
+      throw new Error(
+        `Unsupported deterministic Dart value node: ${value.kind}`,
+      );
+  }
+}
+
+/** Return whether a rendered standalone value is valid in a const initializer. */
+export function isConstDartValueNode(value: RenderableValueNode): boolean {
+  switch (value.kind) {
+    case "numberValueNode":
+    case "booleanValueNode":
+    case "stringValueNode":
+    case "noneValueNode":
+    case "publicKeyValueNode":
+      return true;
+    default:
+      return false;
+  }
+}
+
+function toDartStringLiteral(value: string): string {
+  return `'${value
+    .replaceAll("\\", "\\\\")
+    .replaceAll("\n", "\\n")
+    .replaceAll("\r", "\\r")
+    .replaceAll("\t", "\\t")
+    .replaceAll("\b", "\\b")
+    .replaceAll("\f", "\\f")
+    .replaceAll("$", "\\$")
+    .replaceAll("'", "\\'")}'`;
+}

package/src/visitors/getRenderMapVisitor.ts

@@ -86,7 +86,7 @@ export function getRenderMapVisitor(
         visitRoot(node: RootNode, { self }) {
           const programMaps = [
             visit(node.program, self),
-            ...node.additionalPrograms.map((p) => visit(p, self)),
+            ...(node.additionalPrograms ?? []).map((p) => visit(p, self)),
           ];
 
           const mergedProgramMap = mergeRenderMaps(programMaps);

package/src/visitors/getTypeManifestVisitor.ts

@@ -228,13 +228,18 @@ export function getTypeManifestVisitor(input: {
       const itemManifest = visit(node.item, self);
       const encoderSizeExpr = getArraySizeExpression(node, "Encoder");
       const decoderSizeExpr = getArraySizeExpression(node, "Decoder");
+      const itemType = fragmentFromString(itemManifest.type.content);
+      const itemEncoder = fragment`${use(
+        "transformEncoder",
+        "solanaCodecsCore",
+      )}(${itemManifest.encoder}, (${itemType} value) => value)`;
 
       return {
         type: fragment`List<${itemManifest.type}>`,
         encoder: fragment`${use(
           "getArrayEncoder",
           "solanaCodecsDataStructures",
-        )}(${itemManifest.encoder}${encoderSizeExpr})`,
+        )}(${itemEncoder}${encoderSizeExpr})`,
         decoder: fragment`${use(
           "getArrayDecoder",
           "solanaCodecsDataStructures",
@@ -286,7 +291,7 @@ export function getTypeManifestVisitor(input: {
     },
 
     visitTupleType(node: TupleTypeNode, { self }) {
-      const itemManifests = node.items.map((item) => visit(item, self));
+      const itemManifests = (node.items ?? []).map((item) => visit(item, self));
       const typeList = itemManifests
         .map((m) => m.type.content)
         .join(", ");
@@ -300,19 +305,33 @@ export function getTypeManifestVisitor(input: {
       }
 
       const encoderListStr = encoderList.map((e) => e.content).join(", ");
+      const decoderListStr = decoderList.map((d) => d.content).join(", ");
+      // Two-element tuples render through the typed getTuple2 helpers so the
+      // generated value type is the Dart record `(T1, T2)` rather than a
+      // heterogeneous List<Object?>. Arity-2 is the only shape that currently
+      // appears in supported IDLs; wider tuples stay on the untyped helpers.
+      let tupleEncoderFn = "getTupleEncoder";
+      let tupleDecoderFn = "getTupleDecoder";
+      let tupleEncoderArgs = `[${encoderListStr}]`;
+      let tupleDecoderArgs = `[${decoderListStr}]`;
+      if (itemManifests.length === 2) {
+        tupleEncoderFn = "getTuple2Encoder";
+        tupleDecoderFn = "getTuple2Decoder";
+        tupleEncoderArgs = encoderListStr;
+        tupleDecoderArgs = decoderListStr;
+      }
       const encoderFrag = fragment`${use(
-        "getTupleEncoder",
+        tupleEncoderFn,
         "solanaCodecsDataStructures",
-      )}([${fragmentFromString(encoderListStr)}])`;
+      )}(${tupleEncoderArgs})`;
       for (const e of encoderList) {
         encoderFrag.imports.mergeWith(e.imports);
       }
 
-      const decoderListStr = decoderList.map((d) => d.content).join(", ");
       const decoderFrag = fragment`${use(
-        "getTupleDecoder",
+        tupleDecoderFn,
         "solanaCodecsDataStructures",
-      )}([${fragmentFromString(decoderListStr)}])`;
+      )}(${tupleDecoderArgs})`;
       for (const d of decoderList) {
         decoderFrag.imports.mergeWith(d.imports);
       }
@@ -327,8 +346,9 @@ export function getTypeManifestVisitor(input: {
     },
 
     visitStructType(node: StructTypeNode, { self }) {
-      const fields = node.fields.map((f) => visit(f, self));
-      const fieldNames = node.fields.map((f) => f.name as string);
+      const nodeFields = node.fields ?? [];
+      const fields = nodeFields.map((f) => visit(f, self));
+      const fieldNames = nodeFields.map((f) => f.name as string);
 
       // Type: Map<String, Object?> (for inline structs without a name)
       const typeStr = "Map<String, Object?>";
@@ -371,7 +391,7 @@ export function getTypeManifestVisitor(input: {
 
     visitEnumType(node: EnumTypeNode, { self }) {
       // Check if this is a scalar enum (all empty variants)
-      const isScalar = node.variants.every(
+      const isScalar = (node.variants ?? []).every(
         (v) => v.kind === "enumEmptyVariantTypeNode",
       );
 
@@ -436,7 +456,10 @@ export function getTypeManifestVisitor(input: {
         encoder: fragment`${use(
           "getNullableEncoder",
           "solanaCodecsDataStructures",
-        )}<${fragmentFromString(itemTypeStr)}>(${itemManifest.encoder}${fragmentFromString(prefixExpr)}${fragmentFromString(noneValueExpr)})`,
+        )}<${fragmentFromString(itemTypeStr)}>(${use(
+          "transformEncoder",
+          "solanaCodecsCore",
+        )}(${itemManifest.encoder}, (${fragmentFromString(itemTypeStr)} value) => value)${fragmentFromString(prefixExpr)}${fragmentFromString(noneValueExpr)})`,
         decoder: fragment`${use(
           "getNullableDecoder",
           "solanaCodecsDataStructures",
@@ -498,7 +521,7 @@ export function getTypeManifestVisitor(input: {
         encoder: fragment`${use(
           "fixEncoderSize",
           "solanaCodecsCore",
-        )}(${innerManifest.encoder}, ${fragmentFromString(String(node.size))})`,
+        )}(${innerManifest.encoder}, ${fragmentFromString(String(node.size))}, allowTruncation: false)`,
         decoder: fragment`${use(
           "fixDecoderSize",
           "solanaCodecsCore",
@@ -549,7 +572,7 @@ export function getTypeManifestVisitor(input: {
 
     visitHiddenPrefixType(node: HiddenPrefixTypeNode, { self }) {
       const innerManifest = visit(node.type, self);
-      const prefixes = node.prefix.map((p) => getHiddenAffixManifest(p, self));
+      const prefixes = (node.prefix ?? []).map((p) => getHiddenAffixManifest(p, self));
       const prefixEncoders = prefixes
         .map((p) => p.encoder.content)
         .join(", ");
@@ -584,7 +607,7 @@ export function getTypeManifestVisitor(input: {
 
     visitHiddenSuffixType(node: HiddenSuffixTypeNode, { self }) {
       const innerManifest = visit(node.type, self);
-      const suffixes = node.suffix.map((s) => getHiddenAffixManifest(s, self));
+      const suffixes = (node.suffix ?? []).map((s) => getHiddenAffixManifest(s, self));
       const suffixEncoders = suffixes
         .map((s) => s.encoder.content)
         .join(", ");

package/src/visitors/renderVisitor.ts

@@ -9,6 +9,7 @@ import type { Fragment } from "../utils/fragment.js";
 import type { RenderOptions } from "../utils/options.js";
 import { DartImportMap, DART_EXTERNAL_PACKAGE_MAP } from "../utils/importMap.js";
 import { formatDartDirectory } from "../utils/formatCode.js";
+import { normalizeRootNode } from "../utils/normalizeRootNode.js";
 import { getRenderMapVisitor } from "./getRenderMapVisitor.js";
 
 /**
@@ -29,6 +30,8 @@ export function renderVisitor(
   } = options;
 
   return rootNodeVisitor((root: RootNode) => {
+    const normalizedRoot = normalizeRootNode(root);
+
     // 1. Optionally delete the output directory
     if (deleteFolderBeforeRendering && existsSync(outputDir)) {
       deleteDirectory(outputDir);
@@ -36,7 +39,7 @@ export function renderVisitor(
 
     // 2. Build the render map
     const renderMap = visit(
-      root,
+      normalizedRoot,
       getRenderMapVisitor({ nameApi, dependencyMap }),
     );