@metaplex-foundation/kinobi 0.0.1

package/src/idl/Idl.ts

@@ -0,0 +1,19 @@
+import type { IdlAccount } from './IdlAccount';
+import type { IdlDefinedType } from './IdlDefinedType';
+import type { IdlError } from './IdlError';
+import type { IdlInstruction } from './IdlInstruction';
+
+export type Idl = {
+  version: string;
+  name: string;
+  instructions: IdlInstruction[];
+  accounts?: IdlAccount[];
+  errors?: IdlError[];
+  types?: IdlDefinedType[];
+  metadata: {
+    address: string;
+    origin?: 'anchor' | 'shank';
+    binaryVersion?: string;
+    libVersion?: string;
+  };
+};

package/src/idl/IdlAccount.ts

@@ -0,0 +1,14 @@
+import type { IdlTypeLeaf, IdlTypeStruct } from './IdlType';
+
+export type IdlAccount = {
+  name: string;
+  type: IdlTypeStruct;
+  docs?: string[];
+  seeds?: IdlAccountSeed[];
+  size?: number;
+};
+
+export type IdlAccountSeed =
+  | { kind: 'programId' }
+  | { kind: 'literal'; value: string }
+  | { kind: 'variable'; name: string; description: string; type: IdlTypeLeaf };

package/src/idl/IdlDefinedType.ts

@@ -0,0 +1,7 @@
+import type { IdlTypeEnum, IdlTypeStruct } from './IdlType';
+
+export type IdlDefinedType = {
+  name: string;
+  type: IdlTypeStruct | IdlTypeEnum;
+  docs?: string[];
+};

package/src/idl/IdlError.ts

@@ -0,0 +1,6 @@
+export type IdlError = {
+  code?: number;
+  name?: string;
+  msg?: string;
+  docs?: string[];
+};

package/src/idl/IdlInstruction.ts

@@ -0,0 +1,29 @@
+import type { IdlType } from './IdlType';
+
+export type IdlInstruction = {
+  name: string;
+  accounts: IdlInstructionAccount[];
+  args: IdlInstructionArg[];
+  defaultOptionalAccounts?: boolean;
+  discriminant?: IdlInstructionDiscriminant;
+  docs?: string[];
+};
+
+export type IdlInstructionAccount = {
+  name: string;
+  isMut: boolean;
+  isSigner: boolean;
+  isOptionalSigner?: boolean;
+  desc?: string;
+  optional?: boolean;
+};
+
+export type IdlInstructionArg = {
+  name: string;
+  type: IdlType;
+};
+
+export type IdlInstructionDiscriminant = {
+  type: IdlType;
+  value: number;
+};

package/src/idl/IdlType.ts

@@ -0,0 +1,72 @@
+export type IdlType =
+  | IdlTypeDefinedLink
+  | IdlTypeOption
+  | IdlTypeTuple
+  | IdlTypeVec
+  | IdlTypeArray
+  | IdlTypeMap
+  | IdlTypeSet
+  | IdlTypeStruct
+  | IdlTypeEnum
+  | IdlTypeLeaf;
+
+// Defined.
+export type IdlTypeDefinedLink = { defined: string };
+
+// Options.
+export type IdlTypeOption = { option: IdlType } | { coption: IdlType };
+
+// Lists.
+export type IdlTypeTuple = { tuple: IdlType[] };
+export type IdlTypeVec = { vec: IdlType };
+export type IdlTypeArray = { array: [idlType: IdlType, size: number] };
+
+// Maps.
+export type IdlTypeMap = IdlTypeHashMap | IdlTypeBTreeMap;
+export type IdlTypeHashMap = { hashMap: [IdlType, IdlType] };
+export type IdlTypeBTreeMap = { bTreeMap: [IdlType, IdlType] };
+
+// Sets.
+export type IdlTypeSet = IdlTypeHashSet | IdlTypeBTreeSet;
+export type IdlTypeHashSet = { hashSet: IdlType };
+export type IdlTypeBTreeSet = { bTreeSet: IdlType };
+
+// Struct.
+export type IdlTypeStruct = {
+  kind: 'struct';
+  name?: string;
+  fields: IdlTypeStructField[];
+};
+export type IdlTypeStructField = {
+  name: string;
+  type: IdlType;
+  docs?: string[];
+  defaultsValue?: any;
+};
+
+// Enums.
+export type IdlTypeEnum = {
+  kind: 'enum';
+  name?: string;
+  variants: IdlTypeEnumVariant[];
+};
+export type IdlTypeEnumVariant = { name: string; fields?: IdlTypeEnumFields };
+export type IdlTypeEnumFields = IdlTypeEnumField[] | IdlType[];
+export type IdlTypeEnumField = { name: string; type: IdlType; docs?: string[] };
+
+// Leaves.
+export type IdlTypeLeaf = IdlTypeNumber | 'string' | 'publicKey' | 'bytes';
+export type IdlTypeNumber =
+  | 'bool'
+  | 'u8'
+  | 'u16'
+  | 'u32'
+  | 'u64'
+  | 'u128'
+  | 'i8'
+  | 'i16'
+  | 'i32'
+  | 'i64'
+  | 'i128'
+  | 'f32'
+  | 'f64';

package/src/idl/index.ts

@@ -0,0 +1,6 @@
+export * from './Idl';
+export * from './IdlAccount';
+export * from './IdlDefinedType';
+export * from './IdlError';
+export * from './IdlInstruction';
+export * from './IdlType';

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './idl';
+export * from './Kinobi';
+export * from './nodes';
+export * from './renderers';
+export * from './visitors';

package/src/logs.ts

@@ -0,0 +1,77 @@
+/* eslint-disable no-console */
+import chalk from 'chalk';
+
+const DEFAULT_LOG_LEVEL = 'info';
+export const LOG_LEVELS = ['debug', 'trace', 'info', 'warn', 'error'] as const;
+export type LogLevel = typeof LOG_LEVELS[number];
+
+export const logError = (message: string, hint?: string): void => {
+  if (!shouldLogLevel('error')) return;
+  logMessageAndHint(
+    `${chalk.bgRed.black(' Error ')} ${chalk.redBright(message)}`,
+    hint
+  );
+};
+
+export const logWarn = (message: string, hint?: string): void => {
+  if (!shouldLogLevel('warn')) return;
+  logMessageAndHint(
+    `${chalk.bgYellow.black(' Warning ')} ${chalk.yellow(message)}`,
+    hint
+  );
+};
+
+export const logInfo = (message: string, hint?: string): void => {
+  if (!shouldLogLevel('info')) return;
+  logMessageAndHint(
+    `${chalk.bgBlue.black(' Info ')} ${chalk.blue(message)}`,
+    hint
+  );
+};
+
+export const logTrace = (message: string, hint?: string): void => {
+  if (!shouldLogLevel('trace')) return;
+  logMessageAndHint(
+    `${chalk.bgWhite.black(' Trace ')} ${chalk.white(message)}`,
+    hint
+  );
+};
+
+export const logDebug = (message: string, debug?: any, hint?: string): void => {
+  if (!shouldLogLevel('debug')) return;
+  logMessageAndHint(
+    `${chalk.bgMagentaBright.black(' Debug ')} ${chalk.magentaBright(message)}`,
+    hint,
+    false
+  );
+  if (debug !== undefined) console.log(debug);
+  console.log('\n');
+};
+
+export const getLevelIndex = (level: LogLevel): number =>
+  LOG_LEVELS.indexOf(level);
+
+export const shouldLogLevel = (level: LogLevel): boolean =>
+  getLevelIndex(level) >= getLevelIndex(getMinLogLevel());
+
+const getMinLogLevel = (): LogLevel => {
+  const level = process.env.LOG;
+  if (level && LOG_LEVELS.includes(level as LogLevel)) {
+    return level as LogLevel;
+  }
+  return DEFAULT_LOG_LEVEL;
+};
+
+const logMessageAndHint = (
+  message: string,
+  hint?: string,
+  lineJump = true
+): void => {
+  console.log(message + getDimmedHint(hint) + (lineJump ? '\n' : ''));
+};
+
+const getDimmedHint = (hint?: string, prefix = '|> '): string => {
+  if (!hint) return '';
+  const hintArray = (hint ?? '').split('\n').filter((line) => !!line);
+  return chalk.dim(hintArray.map((h) => `\n${prefix}${h}`).join(''));
+};

package/src/nodes/AccountNode.ts

@@ -0,0 +1,126 @@
+import { mainCase } from '../utils';
+import type { IdlAccount } from '../idl';
+import type { Visitable, Visitor } from '../visitors';
+import type { Node } from './Node';
+import { createTypeNodeFromIdl, TypeNode } from './TypeNode';
+import { assertTypeStructNode, TypeStructNode } from './TypeStructNode';
+import type { InstructionNodeAccountDefaultsSeed } from './InstructionNode';
+import { isTypeLeafNode } from './TypeLeafNode';
+import { TypeStructFieldNode } from './TypeStructFieldNode';
+
+export type AccountNodeMetadata = {
+  readonly name: string;
+  readonly idlName: string;
+  readonly docs: string[];
+  readonly internal: boolean;
+  readonly size: number | null;
+  readonly discriminator: AccountNodeDiscriminator | null;
+  readonly seeds: AccountNodeSeed[];
+};
+
+export type AccountNodeDiscriminator =
+  | { kind: 'field'; name: string }
+  | { kind: 'size' };
+
+export type AccountNodeSeed =
+  | { kind: 'programId' }
+  | { kind: 'literal'; value: string }
+  | { kind: 'variable'; name: string; description: string; type: TypeNode };
+
+export class AccountNode implements Visitable {
+  readonly nodeClass = 'AccountNode' as const;
+
+  readonly metadata: AccountNodeMetadata;
+
+  readonly type: TypeStructNode;
+
+  constructor(metadata: AccountNodeMetadata, type: TypeStructNode) {
+    this.metadata = {
+      ...metadata,
+      name: mainCase(metadata.name),
+      seeds: metadata.seeds.map((seed) =>
+        'name' in seed ? { ...seed, name: mainCase(seed.name) } : seed
+      ),
+    };
+    this.type = type;
+  }
+
+  static fromIdl(idl: Partial<IdlAccount>): AccountNode {
+    const name = idl.name ?? '';
+    const idlStruct = idl.type ?? { kind: 'struct', fields: [] };
+    const type = createTypeNodeFromIdl({ name, ...idlStruct });
+    assertTypeStructNode(type);
+    const seeds = (idl.seeds ?? []).map((seed) => {
+      if (seed.kind === 'variable') {
+        return { ...seed, type: createTypeNodeFromIdl(seed.type) };
+      }
+      return seed;
+    });
+    const metadata = {
+      name,
+      idlName: name,
+      docs: idl.docs ?? [],
+      internal: false,
+      size: idl.size ?? null,
+      discriminator: null,
+      seeds,
+    };
+    return new AccountNode(metadata, type);
+  }
+
+  accept<T>(visitor: Visitor<T>): T {
+    return visitor.visitAccount(this);
+  }
+
+  get name(): string {
+    return this.metadata.name;
+  }
+
+  get docs(): string[] {
+    return this.metadata.docs;
+  }
+
+  get discriminatorField(): TypeStructFieldNode | null {
+    if (this.metadata.discriminator?.kind !== 'field') return null;
+    const { name } = this.metadata.discriminator;
+    return name ? this.type.fields.find((f) => f.name === name) ?? null : null;
+  }
+
+  get variableSeeds(): Extract<AccountNodeSeed, { kind: 'variable' }>[] {
+    return this.metadata.seeds.filter(
+      (seed): seed is Extract<AccountNodeSeed, { kind: 'variable' }> =>
+        seed.kind === 'variable'
+    );
+  }
+
+  get hasVariableSeeds(): boolean {
+    return this.variableSeeds.length > 0;
+  }
+
+  get instructionAccountDefaultSeeds(): Record<
+    string,
+    InstructionNodeAccountDefaultsSeed
+  > {
+    return this.metadata.seeds.reduce((acc, seed) => {
+      if (seed.kind !== 'variable') return acc;
+      if (isTypeLeafNode(seed.type) && seed.type.type === 'publicKey') {
+        acc[seed.name] = { kind: 'account', name: seed.name };
+      } else {
+        acc[seed.name] = { kind: 'arg', name: seed.name };
+      }
+      return acc;
+    }, {} as Record<string, InstructionNodeAccountDefaultsSeed>);
+  }
+}
+
+export function isAccountNode(node: Node | null): node is AccountNode {
+  return !!node && node.nodeClass === 'AccountNode';
+}
+
+export function assertAccountNode(
+  node: Node | null
+): asserts node is AccountNode {
+  if (!isAccountNode(node)) {
+    throw new Error(`Expected AccountNode, got ${node?.nodeClass ?? 'null'}.`);
+  }
+}

package/src/nodes/DefinedTypeNode.ts

@@ -0,0 +1,69 @@
+import { mainCase } from '../utils';
+import type { IdlDefinedType } from '../idl';
+import type { Dependency, Visitable, Visitor } from '../visitors';
+import type { Node } from './Node';
+import type { TypeEnumNode } from './TypeEnumNode';
+import { assertTypeStructOrEnumNode, createTypeNodeFromIdl } from './TypeNode';
+import type { TypeStructNode } from './TypeStructNode';
+
+export type DefinedTypeNodeMetadata = {
+  name: string;
+  idlName: string;
+  docs: string[];
+  importFrom: Dependency;
+  internal: boolean;
+};
+
+export class DefinedTypeNode implements Visitable {
+  readonly nodeClass = 'DefinedTypeNode' as const;
+
+  readonly metadata: DefinedTypeNodeMetadata;
+
+  readonly type: TypeStructNode | TypeEnumNode;
+
+  constructor(
+    metadata: DefinedTypeNodeMetadata,
+    type: TypeStructNode | TypeEnumNode
+  ) {
+    this.metadata = { ...metadata, name: mainCase(metadata.name) };
+    this.type = type;
+  }
+
+  static fromIdl(idl: Partial<IdlDefinedType>): DefinedTypeNode {
+    const name = idl.name ?? '';
+    const docs = idl.docs ?? [];
+    const idlType = idl.type ?? { kind: 'struct', fields: [] };
+    const type = createTypeNodeFromIdl({ name, ...idlType });
+    assertTypeStructOrEnumNode(type);
+    return new DefinedTypeNode(
+      { name, idlName: name, docs, importFrom: 'generated', internal: false },
+      type
+    );
+  }
+
+  accept<T>(visitor: Visitor<T>): T {
+    return visitor.visitDefinedType(this);
+  }
+
+  get name(): string {
+    return this.metadata.name;
+  }
+
+  get docs(): string[] {
+    return this.metadata.docs;
+  }
+}
+
+export function isDefinedTypeNode(node: Node | null): node is DefinedTypeNode {
+  return !!node && node.nodeClass === 'DefinedTypeNode';
+}
+
+export function assertDefinedTypeNode(
+  node: Node | null
+): asserts node is DefinedTypeNode {
+  if (!isDefinedTypeNode(node)) {
+    throw new Error(
+      `Expected DefinedTypeNode, got ${node?.nodeClass ?? 'null'}.`
+    );
+  }
+}

package/src/nodes/ErrorNode.ts

@@ -0,0 +1,57 @@
+import type { IdlError } from '../idl';
+import { mainCase } from '../utils';
+import type { Visitable, Visitor } from '../visitors';
+import type { Node } from './Node';
+
+export type ErrorNodeMetadata = {
+  name: string;
+  idlName: string;
+  docs: string[];
+};
+
+export class ErrorNode implements Visitable {
+  readonly nodeClass = 'ErrorNode' as const;
+
+  readonly metadata: ErrorNodeMetadata;
+
+  readonly code: number;
+
+  readonly message: string;
+
+  constructor(metadata: ErrorNodeMetadata, code: number, message: string) {
+    this.metadata = { ...metadata, name: mainCase(metadata.name) };
+    this.code = code;
+    this.message = message;
+  }
+
+  static fromIdl(idl: Partial<IdlError>): ErrorNode {
+    const name = idl.name ?? '';
+    const code = idl.code ?? -1;
+    const message = idl.msg ?? '';
+    const defaultDocs = [`${name}: '${message}'`];
+    const docs = idl.docs ?? defaultDocs;
+    return new ErrorNode({ name, idlName: name, docs }, code, message);
+  }
+
+  accept<T>(visitor: Visitor<T>): T {
+    return visitor.visitError(this);
+  }
+
+  get name(): string {
+    return this.metadata.name;
+  }
+
+  get docs(): string[] {
+    return this.metadata.docs;
+  }
+}
+
+export function isErrorNode(node: Node | null): node is ErrorNode {
+  return !!node && node.nodeClass === 'ErrorNode';
+}
+
+export function assertErrorNode(node: Node | null): asserts node is ErrorNode {
+  if (!isErrorNode(node)) {
+    throw new Error(`Expected ErrorNode, got ${node?.nodeClass ?? 'null'}.`);
+  }
+}