codama-renderers-dart 0.4.3 → 0.5.1

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/importMap.ts

@@ -77,15 +77,20 @@ export class DartImportMap {
     for (const module of this._imports) {
       // Check internal map first (generated cross-references)
       if (module in internalMap) {
-        uris.add(internalMap[module]);
+        const uri = internalMap[module];
+        if (uri) {
+          uris.add(uri);
+        }
       }
       // Then external package map
       else if (module in DART_EXTERNAL_PACKAGE_MAP) {
         uris.add(DART_EXTERNAL_PACKAGE_MAP[module]);
       }
-      // Assume it's already a raw URI (e.g., "package:..." or relative path)
-      else {
+      // Finally, accept explicit Dart URIs and relative Dart paths.
+      else if (isRawDartImportUri(module)) {
         uris.add(module);
+      } else {
+        throw new Error(`Unresolved Dart import module "${module}"`);
       }
     }
 
@@ -127,3 +132,11 @@ export class DartImportMap {
     return lines.join("\n");
   }
 }
+
+function isRawDartImportUri(module: string): boolean {
+  return (
+    module.startsWith("dart:") ||
+    module.startsWith("package:") ||
+    (module.endsWith(".dart") && !module.includes(":"))
+  );
+}

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

@@ -66,7 +66,7 @@ export interface DartNameApi {
   errorMessageFunction(name: string): string;
   /** Enum variant: `camelCase` */
   enumVariant(name: string): string;
-  /** Sealed class variant (data enum): `PascalCase` */
+  /** Sealed class variant (data enum): `{ParentName}{PascalCase}` */
   sealedClassVariant(parentName: string, variantName: string): string;
   /** File name: `snake_case.dart` */
   fileName(name: string): string;
@@ -97,7 +97,8 @@ export function createDartNameApi(): DartNameApi {
       `${camelCase(programName)}Error${pascalCase(errorName)}`,
     errorMessageFunction: (name) => `get${pascalCase(name)}ErrorMessage`,
     enumVariant: (name) => camelCase(name),
-    sealedClassVariant: (_parentName, variantName) => pascalCase(variantName),
+    sealedClassVariant: (parentName, variantName) =>
+      `${pascalCase(parentName)}${pascalCase(variantName)}`,
     isTypeFunction: (name) => `is${pascalCase(name)}`,
     fileName: (name) => snakeCase(name),
     discriminatorConstant: (name) => `${camelCase(name)}Discriminator`,

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/utils/wellKnownAddresses.ts

@@ -44,10 +44,10 @@ export const WELL_KNOWN_ADDRESSES: ReadonlyMap<string, string> = new Map([
 
   // SPL programs
   ['TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA', 'tokenProgramAddress'],
-  ['TokenzQdBNb4qyze1S1U9AHB8MGXmNK1REkTPT5Z3Y', 'token2022ProgramAddress'],
-  ['ATokenGPvbdGVxr1b2hvZbsiqW5xWH25ef7s3c8BnQKu', 'associatedTokenProgramAddress'],
-  ['Memo1UhkJRfRhVq1sR7Y7Nto1s3J2mXTT3L6Wk4K2m6', 'memoProgramAddress'],
-  ['MemoSq4gqABXKKYWVqKkV3m3kb1cTR7F2UMy9r6kFNK', 'memoLegacyProgramAddress'],
+  ['TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb', 'token2022ProgramAddress'],
+  ['ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL', 'associatedTokenProgramAddress'],
+  ['MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr', 'memoProgramAddress'],
+  ['Memo1UhkJRfHyvLMcVucJwxXeuD728EqVDDwQDxFMNo', 'memoLegacyProgramAddress'],
 
   // Metaplex programs
   ['metaqbxxU9qX8rZXkmUJ7haCrXXz2W1PSUq1Rn3E1od', 'tokenMetadataProgramAddress'],

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);