@kontor/kontor-sdk 1.0.0-alpha.0

package/src/wit/wit-parser/core/utils.test.ts

@@ -0,0 +1,327 @@
+import { expect, test, describe } from "vitest";
+
+import {
+  parseWitParameter,
+  splitParameters,
+  parseFunctionSignature,
+} from "./utils.js";
+import type { ParseOptions } from "./utils.js";
+
+const parseOptions: ParseOptions = {
+  records: {
+    "contract-address": [
+      { name: "name", type: "string" },
+      { name: "height", type: "s64" },
+      { name: "tx-index", type: "s64" },
+    ],
+  },
+};
+
+describe("parseFunctionSignature", () => {
+  test.each([
+    {
+      input:
+        "export fib: func(ctx: borrow<proc-context>, arith-address: contract-address, n: u64) -> u64;",
+      expected: {
+        context: "proc",
+        inputs: [
+          {
+            name: "arith-address",
+            type: "contract-address",
+          },
+          {
+            name: "n",
+            type: "u64",
+          },
+        ],
+        name: "fib",
+        outputs: [
+          {
+            type: "u64",
+          },
+        ],
+        type: "function",
+      },
+    },
+    {
+      input:
+        "export cached-values: func(ctx: borrow<view-context>) -> list<u64>;",
+      expected: {
+        context: "view",
+        inputs: [],
+        name: "cached-values",
+        outputs: [
+          {
+            type: "list<u64>",
+          },
+        ],
+        type: "function",
+      },
+    },
+  ])("parseFunctionSignature($input)", ({ input, expected }) => {
+    expect(parseFunctionSignature(input)).toEqual(expected);
+  });
+});
+
+describe("parseWitParameter", () => {
+  test.each([
+    {
+      parameter: "ctx: borrow<proc-context>",
+      expected: {
+        name: "ctx",
+        type: "borrow<proc-context>",
+      },
+    },
+    {
+      parameter: "arith-address: contract-address",
+      expected: {
+        name: "arith-address",
+        type: "tuple",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    {
+      parameter: "n: u64",
+      expected: {
+        name: "n",
+        type: "u64",
+      },
+    },
+    {
+      parameter: "y: string",
+      expected: {
+        name: "y",
+        type: "string",
+      },
+    },
+    {
+      parameter: "list-of-strings: list<string>",
+      expected: {
+        name: "list-of-strings",
+        type: "list<string>",
+      },
+    },
+    {
+      parameter: "arith-addresses: list<contract-address>",
+      expected: {
+        name: "arith-addresses",
+        type: "list<tuple>",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    {
+      parameter: "list<contract-address>",
+      expected: {
+        type: "list<tuple>",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    {
+      parameter: "option<contract-address>",
+      expected: {
+        type: "option<tuple>",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    {
+      parameter: "result<contract-address, error>",
+      expected: {
+        type: "result<tuple, error>",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    {
+      parameter: "result<list<contract-address>, error>",
+      expected: {
+        type: "result<list<tuple>, error>",
+        components: [
+          { name: "name", type: "string" },
+          { name: "height", type: "s64" },
+          { name: "tx-index", type: "s64" },
+        ],
+      },
+    },
+    // {
+    //   parameter: "result<string, list<option<contract-address>>>",
+    //   expected: {
+    //     type: "result<string, list<option<tuple>>>",
+    //     components: [
+    //       { name: "left", type: "string" },
+    //       {
+    //         name: "right",
+    //         type: "list<option<tuple>>",
+    //         components: [
+    //           { name: "name", type: "string" },
+    //           { name: "height", type: "s64" },
+    //           { name: "tx-index", type: "s64" },
+    //         ],
+    //       },
+    //     ],
+    //   },
+    // },
+    // {
+    //   parameter: "result<string, list<result<string, contract-address>>>",
+    //   expected: {
+    //     type: "result<string, list<result<string, tuple>>>",
+    //     components: [
+    //       { name: "left", type: "string" },
+    //       {
+    //         name: "right",
+    //         type: "list<result<string, tuple>>",
+    //         components: [
+    //           { name: "left", type: "string" },
+    //           {
+    //             name: "right",
+    //             type: "tuple",
+    //             components: [
+    //               { name: "name", type: "string" },
+    //               { name: "height", type: "s64" },
+    //               { name: "tx-index", type: "s64" },
+    //             ],
+    //           },
+    //         ],
+    //       },
+    //     ],
+    //   },
+    // },
+    // {
+    //   parameter:
+    //     "result<string, list<result<string, option<contract-address>>>>",
+    //   expected: {
+    //     type: "result<string, list<result<string, option<tuple>>>>",
+    //     components: [
+    //       { name: "left", type: "string" },
+    //       {
+    //         name: "right",
+    //         type: "list<result<string, option<tuple>>>",
+    //         components: [
+    //           { name: "left", type: "string" },
+    //           {
+    //             name: "right",
+    //             type: "option<tuple>",
+    //             components: [
+    //               { name: "name", type: "string" },
+    //               { name: "height", type: "s64" },
+    //               { name: "tx-index", type: "s64" },
+    //             ],
+    //           },
+    //         ],
+    //       },
+    //     ],
+    //   },
+    // },
+    // {
+    //   parameter: "option<list<result<string, contract-address>>>",
+    //   expected: {
+    //     type: "option<list<result<string, tuple>>>",
+    //     components: [
+    //       { type: "string", name: "left" },
+    //       {
+    //         name: "right",
+    //         type: "tuple",
+    //         components: [
+    //           { type: "string", name: "name" },
+    //           { name: "height", type: "s64" },
+    //           { name: "tx-index", type: "s64" },
+    //         ],
+    //       },
+    //     ],
+    //   },
+    // },
+  ])("parseWitParameter($parameter)", ({ parameter, expected }) => {
+    expect(parseWitParameter(parameter, parseOptions)).toEqual(expected);
+  });
+});
+
+// import { InvalidGenericSyntaxError } from "./errors";
+
+describe("splitParameters (WIT generics, only < > nesting)", () => {
+  test("empty / whitespace", () => {
+    expect(splitParameters("")).toEqual([]);
+    expect(splitParameters("   ")).toEqual([]);
+  });
+
+  test("simple top-level commas", () => {
+    expect(splitParameters("a, b, c")).toEqual(["a", "b", "c"]);
+    expect(splitParameters("  a  ,   b ,c ")).toEqual(["a", "b", "c"]);
+  });
+
+  test("does not split inside < >", () => {
+    expect(splitParameters("tuple<u64, list<string>>")).toEqual([
+      "tuple<u64, list<string>>",
+    ]);
+
+    expect(splitParameters("result<integer, error>")).toEqual([
+      "result<integer, error>",
+    ]);
+
+    expect(splitParameters("map<string, list<result<u64, error>>>")).toEqual([
+      "map<string, list<result<u64, error>>>",
+    ]);
+  });
+
+  test("mixed: top-level params that contain nested generics", () => {
+    const input =
+      "ctx: borrow<proc-context>, pair: list<result<token-pair, error>>, n: u64";
+    expect(splitParameters(input)).toEqual([
+      "ctx: borrow<proc-context>",
+      "pair: list<result<token-pair, error>>",
+      "n: u64",
+    ]);
+  });
+
+  test("deep nesting", () => {
+    const input = "outer<mid<inner<u8, list<u16>>>>";
+    expect(splitParameters(input)).toEqual([
+      "outer<mid<inner<u8, list<u16>>>>",
+    ]);
+  });
+
+  test("handles trailing comma by ignoring empty token", () => {
+    expect(splitParameters("a, b<z, y>,")) // trailing comma
+      .toEqual(["a", "b<z, y>"]);
+  });
+
+  test("ignores empty segments from duplicate commas", () => {
+    expect(splitParameters("a,,b")).toEqual(["a", "b"]);
+    expect(splitParameters(",a,b,")).toEqual(["a", "b"]);
+  });
+
+  test("throws on unbalanced opener", () => {
+    expect(() => splitParameters("a<b,c")).toThrow(); // e.g., InvalidGenericSyntaxError
+  });
+
+  test("throws on stray closer", () => {
+    expect(() => splitParameters("a,b>")).toThrow();
+  });
+
+  test("complex function-style params", () => {
+    const input =
+      "ctx: borrow<proc-context>, result: result<tuple<u64, list<string>>, error>, flag: bool";
+    expect(splitParameters(input)).toEqual([
+      "ctx: borrow<proc-context>",
+      "result: result<tuple<u64, list<string>>, error>",
+      "flag: bool",
+    ]);
+  });
+});

package/src/wit/wit-parser/core/utils.ts

@@ -0,0 +1,268 @@
+import type { WitItemType, WitParameter } from "../../wit.js";
+import { execTyped, isGenericRegex } from "../../regex.js";
+import {
+  InvalidWitParameterError,
+  WitProtectedKeywordError,
+} from "./errors/wit-parameter.js";
+import {
+  InvalidSignatureError,
+  UnknownSignatureError,
+} from "./errors/signature.js";
+import { InvalidGenericDepthError } from "./errors/splitParameters.js";
+import { execFunctionSignature, isFunctionSignature } from "./signatures.js";
+import type { RecordLookup } from "./types/records.js";
+
+export type ParseOptions = {
+  records?: RecordLookup;
+  type?: WitItemType | "record";
+};
+//
+// export const witParameterRegex =
+//   /^(?:(?<name>[a-z][a-z0-9-]*)\s*:\s*)?(?<type>(?:borrow|list|option|result|tuple)\s*<[\s\S]+>|[a-z][a-z0-9-]*|(?:record|variant|flags|enum)\s*\{[\s\S]*\})$/;
+//
+export const witParameterRegex =
+  /^(?:(?<name>[a-z][a-z0-9-]*)\s*:\s*)?(?<type>_|(?:borrow|list|option|result|tuple)\s*<[\s\S]+>|[a-z][a-z0-9-]*|(?:record|variant|flags|enum)\s*\{[\s\S]*\})$/;
+
+export function isGeneric(type: string): boolean {
+  return isGenericRegex.test(type.trim());
+}
+
+export function execGeneric<T extends { outer: string; inner: string }>(
+  type: string,
+) {
+  const m = type.trim().match(isGenericRegex);
+  if (!m || !m.groups) return null;
+  return m.groups as unknown as T;
+}
+
+export function parseWitParameter(param: string, options?: ParseOptions) {
+  // TODO: cache
+  // const parameterCacheKey = getParameterCacheKey(
+  //   param,
+  //   options?.type,
+  //   options?.structs,
+  // );
+  // if (parameterCache.has(parameterCacheKey))
+  //   return parameterCache.get(parameterCacheKey)!;
+  //
+  //
+
+  const match = execTyped<{
+    array?: string;
+    name?: string;
+    type: string;
+  }>(witParameterRegex, param);
+
+  if (!match) throw new InvalidWitParameterError({ param });
+
+  const isGenericType = isGeneric(match.type);
+
+  if (match.name && isWitKeyword(match.name))
+    throw new WitProtectedKeywordError({ param, name: match.name });
+
+  // TODO: smell
+  const name = match.name ? { name: match.name } : {};
+  const records = options?.records ?? {};
+  let type: string;
+  let components = {};
+  if (isGenericType) {
+    const g = execGeneric<{ outer: string; inner: string }>(match.type)!;
+    const parts = splitParameters(g.inner);
+
+    const parsed = parts.map((p) => parseWitParameter(p, { records }));
+
+    // normalize inner types for the outer type string
+    const innerTypeSig = parsed.map((x) => x.type).join(", ");
+
+    switch (g.outer) {
+      case "list":
+      case "option": {
+        if (parsed.length !== 1) {
+          throw new InvalidWitParameterError({
+            param,
+          });
+        }
+        const t = parsed[0]!;
+        type = `${g.outer}<${t.type}>`;
+
+        // flatten record fields for list/option only
+        components = t.components ? { components: t.components } : {};
+        break;
+      }
+
+      case "result": {
+        if (parsed.length !== 2) {
+          throw new InvalidWitParameterError({
+            param,
+          });
+        }
+        const left = parsed[0]!;
+        // @ts-ignore
+        const right = parsed[1]!;
+
+        type = `result<${innerTypeSig}>`;
+
+        components = {
+          ...(left.components && { components: left.components }),
+          // components: [
+          //
+          //   {
+          //     name: "left",
+          //     type: left.type,
+          //     ...(left.components && { components: left.components }),
+          //   },
+          //   {
+          //     name: "right",
+          //     type: right.type,
+          //     ...(right.components && { components: right.components }),
+          //   },
+          // ],
+        };
+
+        // the right / error channel is always assumed to be wit built-in `error` primitive
+        // components = {
+        //   components: [
+        //     {
+        //       name: "left",
+        //       type: left.type,
+        //       ...(left.components && { components: left.components }),
+        //     },
+        //     {
+        //       name: "right",
+        //       type: right.type,
+        //       ...(right.components && { components: right.components }),
+        //     },
+        //   ],
+        // };
+        break;
+      }
+
+      default: {
+        type = `${g.outer}<${innerTypeSig}>`;
+        components = {};
+      }
+    }
+  } else if (match.type in records) {
+    // scalar that maps to a record in `records`
+    type = "tuple";
+    components = { components: records[match.type] };
+  } else {
+    type = match.type;
+  }
+
+  const witParameter: WitParameter = {
+    type: `${type}${match.array ?? ""}`,
+    ...(name as { name: string }),
+    ...components,
+  };
+  // parameterCache.set(parameterCacheKey, witParameter);
+  //
+
+  return witParameter;
+}
+export const witKeywordRegex =
+  /^(?:package|world|interface|contract|include|use|import|export|func|borrow|record|list|enum|flags|variant|option|result|tuple|bool|s8|s16|s32|s64|u8|u16|u32|u64|f32|f64|char|string)$/;
+
+export function isWitKeyword(word: string): boolean {
+  return witKeywordRegex.test(word);
+}
+
+// class InvalidParenthesisError extends Error { constructor(public info: { current: string; depth: number }) { super('Unbalanced <>'); } }
+
+export function splitParameters(
+  params: string,
+  result: string[] = [],
+): readonly string[] {
+  const s = params.trim();
+  if (s.length === 0) return result;
+
+  let current = "";
+  let depth = 0; // nesting depth for <...>
+
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i]!;
+
+    if (ch === "<") {
+      depth += 1;
+      current += ch;
+      continue;
+    }
+    if (ch === ">") {
+      depth -= 1;
+      if (depth < 0)
+        throw new InvalidGenericDepthError({
+          current: s.slice(0, i + 1),
+          depth,
+        });
+      current += ch;
+      continue;
+    }
+    if (ch === "," && depth === 0) {
+      const tok = current.trim();
+      if (tok.length) result.push(tok);
+      current = "";
+      continue;
+    }
+
+    current += ch;
+  }
+
+  if (depth !== 0) throw new InvalidGenericDepthError({ current, depth });
+  const tail = current.trim();
+  if (tail.length) result.push(tail);
+  return result;
+}
+
+export function parseSignature(signature: string, structs: RecordLookup = {}) {
+  if (isFunctionSignature(signature))
+    return parseFunctionSignature(signature, structs);
+
+  throw new UnknownSignatureError({ signature });
+}
+
+export function parseFunctionSignature(
+  signature: string,
+  records: RecordLookup = {},
+) {
+  const match = execFunctionSignature(signature);
+  if (!match) throw new InvalidSignatureError({ signature, type: "func" });
+
+  const inputParams = splitParameters(match.parameters);
+  const inputs = [];
+  const inputLength = inputParams.length;
+  for (let i = 0; i < inputLength; i++) {
+    inputs.push(
+      parseWitParameter(inputParams[i]!, {
+        records,
+      }),
+    );
+  }
+
+  const outputs = [];
+  if (match.returns) {
+    const outputParams = splitParameters(match.returns);
+    const outputLength = outputParams.length;
+    for (let i = 0; i < outputLength; i++) {
+      outputs.push(
+        parseWitParameter(outputParams[i]!, {
+          records,
+        }),
+      );
+    }
+  }
+
+  const contextInput = inputs.shift();
+
+  return {
+    name: match.name,
+    type: "function",
+    context:
+      contextInput?.type === "borrow<proc-context>"
+        ? "proc"
+        : contextInput?.type === "borrow<view-context>"
+          ? "view"
+          : "core",
+    inputs,
+    outputs,
+  };
+}