codama-renderers-dart 0.2.0

package/src/utils/fragment.ts

@@ -0,0 +1,83 @@
+import type { BaseFragment } from "@codama/renderers-core";
+
+import { DartImportMap } from "./importMap.js";
+
+/**
+ * A Fragment represents a piece of generated Dart code
+ * along with the imports it requires.
+ */
+export type Fragment = BaseFragment &
+  Readonly<{
+    imports: DartImportMap;
+  }>;
+
+/**
+ * Create a Fragment from a tagged template literal.
+ * Embedded Fragment values have their imports merged automatically.
+ */
+export function fragment(
+  strings: TemplateStringsArray,
+  ...values: (Fragment | string | number | boolean | undefined | null)[]
+): Fragment {
+  const imports = new DartImportMap();
+  const parts: string[] = [];
+
+  for (let i = 0; i < strings.length; i++) {
+    parts.push(strings[i]);
+    if (i < values.length) {
+      const value = values[i];
+      if (value != null && typeof value === "object" && "imports" in value) {
+        parts.push(value.content);
+        imports.mergeWith(value.imports);
+      } else {
+        parts.push(String(value ?? ""));
+      }
+    }
+  }
+
+  return {
+    content: parts.join(""),
+    imports,
+  };
+}
+
+/**
+ * Create an empty fragment.
+ */
+export function emptyFragment(): Fragment {
+  return { content: "", imports: new DartImportMap() };
+}
+
+/**
+ * Create a fragment from a raw string.
+ */
+export function fragmentFromString(content: string): Fragment {
+  return { content, imports: new DartImportMap() };
+}
+
+/**
+ * Merge multiple fragments with a joiner function.
+ */
+export function mergeFragments(
+  fragments: Fragment[],
+  joiner: (contents: string[]) => string,
+): Fragment {
+  const imports = new DartImportMap();
+  const contents: string[] = [];
+
+  for (const frag of fragments) {
+    contents.push(frag.content);
+    imports.mergeWith(frag.imports);
+  }
+
+  return { content: joiner(contents), imports };
+}
+
+/**
+ * Helper to add a Dart import to a fragment and return a type name fragment.
+ */
+export function use(typeName: string, module: string): Fragment {
+  const imports = new DartImportMap();
+  imports.add(module);
+  return { content: typeName, imports };
+}

package/src/utils/importMap.ts

@@ -0,0 +1,129 @@
+/**
+ * Maps logical module names to Dart package: URIs.
+ */
+export const DART_EXTERNAL_PACKAGE_MAP: Record<string, string> = {
+  // Dart core
+  dartTypedData: "dart:typed_data",
+  dartConvert: "dart:convert",
+  meta: "package:meta/meta.dart",
+
+  // solana_kit packages
+  solanaAddresses: "package:solana_kit_addresses/solana_kit_addresses.dart",
+  solanaCodecsCore: "package:solana_kit_codecs_core/solana_kit_codecs_core.dart",
+  solanaCodecsDataStructures:
+    "package:solana_kit_codecs_data_structures/solana_kit_codecs_data_structures.dart",
+  solanaCodecsNumbers:
+    "package:solana_kit_codecs_numbers/solana_kit_codecs_numbers.dart",
+  solanaCodecsStrings:
+    "package:solana_kit_codecs_strings/solana_kit_codecs_strings.dart",
+  solanaErrors: "package:solana_kit_errors/solana_kit_errors.dart",
+  solanaAccounts: "package:solana_kit_accounts/solana_kit_accounts.dart",
+  solanaInstructions:
+    "package:solana_kit_instructions/solana_kit_instructions.dart",
+  solanaPrograms: "package:solana_kit_programs/solana_kit_programs.dart",
+  solanaRpcTypes: "package:solana_kit_rpc_types/solana_kit_rpc_types.dart",
+  solanaSigners: "package:solana_kit_signers/solana_kit_signers.dart",
+};
+
+/**
+ * Tracks Dart import URIs needed by generated code.
+ *
+ * Dart imports entire libraries (not individual symbols), so we only
+ * need to track which package URIs are used, not specific symbols.
+ */
+export class DartImportMap {
+  private _imports = new Set<string>();
+
+  /**
+   * Add a logical module name (resolved via DART_EXTERNAL_PACKAGE_MAP)
+   * or a raw Dart import URI.
+   */
+  add(module: string): this {
+    this._imports.add(module);
+    return this;
+  }
+
+  /**
+   * Merge another DartImportMap into this one.
+   */
+  mergeWith(other: DartImportMap): this {
+    for (const imp of other._imports) {
+      this._imports.add(imp);
+    }
+    return this;
+  }
+
+  /**
+   * Check if this import map is empty.
+   */
+  get isEmpty(): boolean {
+    return this._imports.size === 0;
+  }
+
+  /**
+   * Get all raw module keys.
+   */
+  get modules(): Set<string> {
+    return new Set(this._imports);
+  }
+
+  /**
+   * Resolve all imports to Dart import URIs and return them sorted.
+   * @param internalMap Maps logical names to relative file paths for generated code cross-references.
+   */
+  resolve(internalMap: Record<string, string> = {}): string[] {
+    const uris = new Set<string>();
+
+    for (const module of this._imports) {
+      // Check internal map first (generated cross-references)
+      if (module in internalMap) {
+        uris.add(internalMap[module]);
+      }
+      // 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 {
+        uris.add(module);
+      }
+    }
+
+    // Sort: dart: first, then package:, then relative
+    return [...uris].sort((a, b) => {
+      const aWeight = a.startsWith("dart:") ? 0 : a.startsWith("package:") ? 1 : 2;
+      const bWeight = b.startsWith("dart:") ? 0 : b.startsWith("package:") ? 1 : 2;
+      if (aWeight !== bWeight) return aWeight - bWeight;
+      return a.localeCompare(b);
+    });
+  }
+
+  /**
+   * Render all imports as Dart import statements.
+   */
+  toString(internalMap: Record<string, string> = {}): string {
+    const resolved = this.resolve(internalMap);
+    if (resolved.length === 0) return "";
+
+    const lines: string[] = [];
+    let lastPrefix = "";
+
+    for (const uri of resolved) {
+      const prefix = uri.startsWith("dart:")
+        ? "dart"
+        : uri.startsWith("package:")
+          ? "package"
+          : "relative";
+
+      // Add blank line between groups
+      if (lastPrefix && lastPrefix !== prefix) {
+        lines.push("");
+      }
+      lastPrefix = prefix;
+
+      lines.push(`import '${uri}';`);
+    }
+
+    return lines.join("\n");
+  }
+}

package/src/utils/index.ts

@@ -0,0 +1,7 @@
+export * from "./codecs.js";
+export * from "./formatCode.js";
+export * from "./fragment.js";
+export * from "./importMap.js";
+export * from "./nameTransformers.js";
+export * from "./options.js";
+export * from "./typeManifest.js";

package/src/utils/nameTransformers.ts

@@ -0,0 +1,112 @@
+import type { CamelCaseString } from "@codama/nodes";
+
+/**
+ * Naming convention transformers for Dart code generation.
+ */
+
+/** Convert a string to PascalCase */
+export function pascalCase(str: string): string {
+  return str
+    .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ""))
+    .replace(/^(.)/, (c) => c.toUpperCase());
+}
+
+/** Convert a string to camelCase */
+export function camelCase(str: string): string {
+  const pascal = pascalCase(str);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+/** Convert a string to snake_case */
+export function snakeCase(str: string): string {
+  return str
+    .replace(/([A-Z])/g, "_$1")
+    .replace(/[-\s]+/g, "_")
+    .replace(/^_/, "")
+    .replace(/_+/g, "_")
+    .toLowerCase();
+}
+
+/** Convert a string to SCREAMING_SNAKE_CASE */
+export function screamingSnakeCase(str: string): string {
+  return snakeCase(str).toUpperCase();
+}
+
+/**
+ * All name transformation functions for Dart code generation.
+ */
+export interface DartNameApi {
+  /** Data class name: `PascalCase` */
+  dataType(name: string): string;
+  /** Encoder function name: `get{PascalCase}Encoder` */
+  encoderFunction(name: string): string;
+  /** Decoder function name: `get{PascalCase}Decoder` */
+  decoderFunction(name: string): string;
+  /** Codec function name: `get{PascalCase}Codec` */
+  codecFunction(name: string): string;
+  /** Account fetch function: `fetch{PascalCase}` */
+  accountFetchFunction(name: string): string;
+  /** Account fetch maybe function: `fetchMaybe{PascalCase}` */
+  accountFetchMaybeFunction(name: string): string;
+  /** Account decode function: `decode{PascalCase}` */
+  accountDecodeFunction(name: string): string;
+  /** Account size constant: `{camelCase}Size` */
+  accountSizeConstant(name: string): string;
+  /** PDA finder function: `find{PascalCase}Pda` */
+  pdaFindFunction(name: string): string;
+  /** Instruction builder function: `get{PascalCase}Instruction` */
+  instructionFunction(name: string): string;
+  /** Instruction parse function: `parse{PascalCase}Instruction` */
+  instructionParseFunction(name: string): string;
+  /** Program address constant: `{camelCase}ProgramAddress` */
+  programAddressConstant(name: string): string;
+  /** Error code constant: `{programName}Error{PascalCase}` */
+  errorConstant(programName: string, errorName: string): string;
+  /** Error message function: `get{PascalCase}ErrorMessage` */
+  errorMessageFunction(name: string): string;
+  /** Enum variant: `camelCase` */
+  enumVariant(name: string): string;
+  /** Sealed class variant (data enum): `PascalCase` */
+  sealedClassVariant(parentName: string, variantName: string): string;
+  /** File name: `snake_case.dart` */
+  fileName(name: string): string;
+  /** Discriminator constant: `{camelCase}Discriminator` */
+  discriminatorConstant(name: string): string;
+  /** isX() helper for type check: `is{PascalCase}` */
+  isTypeFunction(name: string): string;
+}
+
+/**
+ * Create the default Dart name API.
+ */
+export function createDartNameApi(): DartNameApi {
+  return {
+    dataType: (name) => pascalCase(name),
+    encoderFunction: (name) => `get${pascalCase(name)}Encoder`,
+    decoderFunction: (name) => `get${pascalCase(name)}Decoder`,
+    codecFunction: (name) => `get${pascalCase(name)}Codec`,
+    accountFetchFunction: (name) => `fetch${pascalCase(name)}`,
+    accountFetchMaybeFunction: (name) => `fetchMaybe${pascalCase(name)}`,
+    accountDecodeFunction: (name) => `decode${pascalCase(name)}`,
+    accountSizeConstant: (name) => `${camelCase(name)}Size`,
+    pdaFindFunction: (name) => `find${pascalCase(name)}Pda`,
+    instructionFunction: (name) => `get${pascalCase(name)}Instruction`,
+    instructionParseFunction: (name) => `parse${pascalCase(name)}Instruction`,
+    programAddressConstant: (name) => `${camelCase(name)}ProgramAddress`,
+    errorConstant: (programName, errorName) =>
+      `${camelCase(programName)}Error${pascalCase(errorName)}`,
+    errorMessageFunction: (name) => `get${pascalCase(name)}ErrorMessage`,
+    enumVariant: (name) => camelCase(name),
+    sealedClassVariant: (_parentName, variantName) => pascalCase(variantName),
+    isTypeFunction: (name) => `is${pascalCase(name)}`,
+    fileName: (name) => snakeCase(name),
+    discriminatorConstant: (name) => `${camelCase(name)}Discriminator`,
+  };
+}
+
+/**
+ * Convert a CamelCaseString to a regular string.
+ */
+export function fromCamelCaseString(str: CamelCaseString): string {
+  return str as string;
+}

package/src/utils/options.ts

@@ -0,0 +1,46 @@
+import type {
+  LinkableDictionary,
+} from "@codama/visitors-core";
+
+import type { DartNameApi } from "./nameTransformers.js";
+import type { TypeManifestVisitor } from "../visitors/getTypeManifestVisitor.js";
+
+/**
+ * Options for the top-level renderVisitor.
+ */
+export interface RenderOptions extends GetRenderMapOptions {
+  /** Whether to delete the output folder before rendering. Default: true. */
+  deleteFolderBeforeRendering?: boolean;
+  /** Whether to run `dart format` on generated files. Default: false. */
+  formatCode?: boolean;
+  /** The Dart package name for pubspec.yaml generation. */
+  dartPackageName?: string;
+  /** Custom dependency overrides for the generated pubspec.yaml. */
+  dartDependencies?: Record<string, string>;
+}
+
+/**
+ * Options for the getRenderMapVisitor.
+ */
+export interface GetRenderMapOptions {
+  /** Custom name API overrides. */
+  nameApi?: Partial<DartNameApi>;
+  /** Dependency map overrides (logical module -> Dart package URI). */
+  dependencyMap?: Record<string, string>;
+}
+
+/**
+ * Shared rendering context passed to fragment generators.
+ */
+export interface RenderScope {
+  /** The resolved name API for Dart naming conventions. */
+  nameApi: DartNameApi;
+  /** The type manifest visitor for resolving type nodes. */
+  typeManifestVisitor: TypeManifestVisitor;
+  /** Linkable nodes dictionary for cross-references. */
+  linkables: LinkableDictionary;
+  /** Custom dependency map. */
+  dependencyMap: Record<string, string>;
+  /** Internal import map (logical name -> relative file path). */
+  internalImportMap: Record<string, string>;
+}

package/src/utils/typeManifest.ts

@@ -0,0 +1,31 @@
+import type { Fragment } from "./fragment.js";
+import { emptyFragment } from "./fragment.js";
+
+/**
+ * Represents how a Codama type maps to Dart types and codec expressions.
+ */
+export interface TypeManifest {
+  /** The Dart type name (e.g. `int`, `BigInt`, `Address`, `MyStruct`). */
+  type: Fragment;
+  /** The Dart encoder expression (e.g. `getU8Encoder()`). */
+  encoder: Fragment;
+  /** The Dart decoder expression (e.g. `getU8Decoder()`). */
+  decoder: Fragment;
+  /** The Dart value expression for default values. */
+  value: Fragment;
+  /** Whether this is a scalar enum (Dart `enum`). */
+  isEnum: boolean;
+}
+
+/**
+ * Create an empty TypeManifest.
+ */
+export function emptyTypeManifest(): TypeManifest {
+  return {
+    type: emptyFragment(),
+    encoder: emptyFragment(),
+    decoder: emptyFragment(),
+    value: emptyFragment(),
+    isEnum: false,
+  };
+}

package/src/visitors/getRenderMapVisitor.ts

@@ -0,0 +1,272 @@
+import {
+  type AccountNode,
+  type DefinedTypeNode,
+  type InstructionNode,
+  type PdaNode,
+  type ProgramNode,
+  type RootNode,
+} from "@codama/nodes";
+import {
+  type RenderMap,
+  addToRenderMap,
+  createRenderMap,
+  mergeRenderMaps,
+} from "@codama/renderers-core";
+import {
+  type Visitor,
+  LinkableDictionary,
+  NodeStack,
+  extendVisitor,
+  pipe,
+  recordLinkablesOnFirstVisitVisitor,
+  recordNodeStackVisitor,
+  staticVisitor,
+  visit,
+} from "@codama/visitors-core";
+
+import type { Fragment } from "../utils/fragment.js";
+import type { GetRenderMapOptions, RenderScope } from "../utils/options.js";
+import { createDartNameApi } from "../utils/nameTransformers.js";
+import { snakeCase } from "../utils/nameTransformers.js";
+import { getTypeManifestVisitor } from "./getTypeManifestVisitor.js";
+
+import { getAccountPageFragment } from "../fragments/accountPage.js";
+import { getErrorPageFragment } from "../fragments/errorPage.js";
+import { getIndexPageFragment, getRootIndexPageFragment } from "../fragments/indexPage.js";
+import { getInstructionPageFragment } from "../fragments/instructionPage.js";
+import { getPdaPageFragment } from "../fragments/pdaPage.js";
+import { getProgramPageFragment } from "../fragments/programPage.js";
+import { getTypePageFragment } from "../fragments/typePage.js";
+
+/**
+ * Creates a visitor that maps Codama nodes to a RenderMap of Dart files.
+ */
+export function getRenderMapVisitor(
+  options: GetRenderMapOptions = {},
+): Visitor<RenderMap<Fragment>, "rootNode" | "programNode" | "accountNode" | "definedTypeNode" | "instructionNode" | "pdaNode"> {
+  const nameApi = {
+    ...createDartNameApi(),
+    ...options.nameApi,
+  };
+  const dependencyMap = options.dependencyMap ?? {};
+
+  const stack = new NodeStack();
+  const linkables = new LinkableDictionary();
+
+  const typeManifestVisitor = getTypeManifestVisitor({
+    nameApi,
+    linkables,
+    stack,
+  });
+
+  const scope: RenderScope = {
+    nameApi,
+    typeManifestVisitor,
+    linkables,
+    dependencyMap,
+    internalImportMap: {},
+  };
+
+  return pipe(
+    staticVisitor(
+      () => createRenderMap<Fragment>(),
+      {
+        keys: [
+          "rootNode",
+          "programNode",
+          "accountNode",
+          "definedTypeNode",
+          "instructionNode",
+          "pdaNode",
+        ],
+      },
+    ),
+    (v) =>
+      extendVisitor(v, {
+        visitRoot(node: RootNode, { self }) {
+          const programMaps = [
+            visit(node.program, self),
+            ...node.additionalPrograms.map((p) => visit(p, self)),
+          ];
+
+          return mergeRenderMaps(programMaps);
+        },
+
+        visitProgram(node: ProgramNode, { self }) {
+          const programName = node.name as string;
+          const maps: RenderMap<Fragment>[] = [];
+
+          // Track file names for barrel exports
+          const accountFiles: string[] = [];
+          const instructionFiles: string[] = [];
+          const typeFiles: string[] = [];
+          const pdaFiles: string[] = [];
+          const errorFiles: string[] = [];
+          const programFiles: string[] = [];
+
+          // Visit accounts
+          for (const account of node.accounts ?? []) {
+            maps.push(visit(account, self));
+            accountFiles.push(`${snakeCase(account.name as string)}.dart`);
+          }
+
+          // Visit instructions
+          for (const instruction of node.instructions ?? []) {
+            maps.push(visit(instruction, self));
+            instructionFiles.push(
+              `${snakeCase(instruction.name as string)}.dart`,
+            );
+          }
+
+          // Visit defined types
+          for (const definedType of node.definedTypes ?? []) {
+            maps.push(visit(definedType, self));
+            typeFiles.push(
+              `${snakeCase(definedType.name as string)}.dart`,
+            );
+          }
+
+          // Visit PDAs
+          for (const pda of node.pdas ?? []) {
+            maps.push(visit(pda, self));
+            pdaFiles.push(`${snakeCase(pda.name as string)}.dart`);
+          }
+
+          // Program page
+          const programFragment = getProgramPageFragment(node, scope);
+          const programFileName = `${snakeCase(programName)}.dart`;
+          programFiles.push(programFileName);
+          let programMap = createRenderMap<Fragment>();
+          programMap = addToRenderMap(programMap, `programs/${programFileName}`, programFragment);
+          maps.push(programMap);
+
+          // Error page
+          const errors = node.errors ?? [];
+          if (errors.length > 0) {
+            const errorFragment = getErrorPageFragment(node, scope);
+            const errorFileName = `${snakeCase(programName)}.dart`;
+            errorFiles.push(errorFileName);
+            let errorMap = createRenderMap<Fragment>();
+            errorMap = addToRenderMap(errorMap, `errors/${errorFileName}`, errorFragment);
+            maps.push(errorMap);
+          }
+
+          // Barrel exports
+          const categories: string[] = [];
+
+          if (accountFiles.length > 0) {
+            categories.push("accounts");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "accounts/accounts.dart",
+              getIndexPageFragment(accountFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          if (instructionFiles.length > 0) {
+            categories.push("instructions");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "instructions/instructions.dart",
+              getIndexPageFragment(instructionFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          if (typeFiles.length > 0) {
+            categories.push("types");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "types/types.dart",
+              getIndexPageFragment(typeFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          if (pdaFiles.length > 0) {
+            categories.push("pdas");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "pdas/pdas.dart",
+              getIndexPageFragment(pdaFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          if (errorFiles.length > 0) {
+            categories.push("errors");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "errors/errors.dart",
+              getIndexPageFragment(errorFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          if (programFiles.length > 0) {
+            categories.push("programs");
+            let indexMap = createRenderMap<Fragment>();
+            indexMap = addToRenderMap(
+              indexMap,
+              "programs/programs.dart",
+              getIndexPageFragment(programFiles),
+            );
+            maps.push(indexMap);
+          }
+
+          // Root barrel
+          if (categories.length > 0) {
+            let rootMap = createRenderMap<Fragment>();
+            rootMap = addToRenderMap(
+              rootMap,
+              `${snakeCase(programName)}.dart`,
+              getRootIndexPageFragment(categories),
+            );
+            maps.push(rootMap);
+          }
+
+          return mergeRenderMaps(maps);
+        },
+
+        visitAccount(node: AccountNode, { self }) {
+          const fileName = `${snakeCase(node.name as string)}.dart`;
+          const frag = getAccountPageFragment(node, scope);
+          let map = createRenderMap<Fragment>();
+          map = addToRenderMap(map, `accounts/${fileName}`, frag);
+          return map;
+        },
+
+        visitDefinedType(node: DefinedTypeNode, { self }) {
+          const fileName = `${snakeCase(node.name as string)}.dart`;
+          const frag = getTypePageFragment(node, scope);
+          let map = createRenderMap<Fragment>();
+          map = addToRenderMap(map, `types/${fileName}`, frag);
+          return map;
+        },
+
+        visitInstruction(node: InstructionNode, { self }) {
+          const fileName = `${snakeCase(node.name as string)}.dart`;
+          const frag = getInstructionPageFragment(node, scope);
+          let map = createRenderMap<Fragment>();
+          map = addToRenderMap(map, `instructions/${fileName}`, frag);
+          return map;
+        },
+
+        visitPda(node: PdaNode, { self }) {
+          const fileName = `${snakeCase(node.name as string)}.dart`;
+          const frag = getPdaPageFragment(node, scope);
+          let map = createRenderMap<Fragment>();
+          map = addToRenderMap(map, `pdas/${fileName}`, frag);
+          return map;
+        },
+      }),
+    (v) => recordNodeStackVisitor(v, stack),
+    (v) => recordLinkablesOnFirstVisitVisitor(v, linkables),
+  );
+}