@xlr-lib/xlr-converters 0.1.1--canary.9.190

package/src/__tests__/annotations.test.ts

@@ -0,0 +1,40 @@
+import { test, expect, describe } from "vitest";
+import { setupTestEnv } from "@xlr-lib/test-utils";
+import { decorateNode } from "../ts/annotations";
+
+describe("Annotations", () => {
+  test("JSDoc comments to strings", () => {
+    const sc = `
+    /**
+   * An asset is the smallest unit of user interaction in a player view
+   * @example Example usage of interface Asset
+   * @see Asset for implementation details
+   * @default default value
+   */
+  export interface Asset<T extends string = string> {
+    id: string;
+    [key: string]: unknown;
+  }
+  `;
+
+    const { sf } = setupTestEnv(sc);
+    expect(decorateNode(sf.statements[0])).toMatchSnapshot();
+  });
+
+  test("JSDoc @meta", () => {
+    const sc = `
+    /**
+   * An asset is the smallest unit of user interaction in a player view
+   * @meta category:views
+   * @meta screenshot:/path/image.png
+   */
+  export interface Asset<T extends string = string> {
+    id: string;
+    [key: string]: unknown;
+  }
+  `;
+
+    const { sf } = setupTestEnv(sc);
+    expect(decorateNode(sf.statements[0])).toMatchSnapshot();
+  });
+});

package/src/__tests__/common-to-ts.test.ts

@@ -0,0 +1,356 @@
+import { test, describe, expect, vi } from "vitest";
+import type { NamedType } from "@xlr-lib/xlr";
+import ts from "typescript";
+import { TSWriter } from "../ts/xlr-to-ts";
+
+describe("Type Exports", () => {
+  vi.setConfig({
+    testTimeout: 2 * 60 * 10000,
+  });
+
+  test("Basic Type Conversion", () => {
+    const xlr = {
+      name: "ActionAsset",
+      type: "object",
+      source: "common-to-ts.test.ts",
+      properties: {
+        value: {
+          required: false,
+          node: {
+            type: "string",
+            title: "ActionAsset.value",
+            description:
+              "The transition value of the action in the state machine",
+          },
+        },
+        label: {
+          required: false,
+          node: {
+            type: "ref",
+            ref: "AssetWrapper<AnyTextAsset>",
+            genericArguments: [
+              {
+                type: "ref",
+                ref: "AnyTextAsset",
+              },
+            ],
+            title: "ActionAsset.label",
+            description: "A text-like asset for the action's label",
+          },
+        },
+        exp: {
+          required: false,
+          node: {
+            type: "ref",
+            ref: "Expression",
+            title: "ActionAsset.exp",
+            description:
+              "An optional expression to execute before transitioning",
+          },
+        },
+        accessibility: {
+          required: false,
+          node: {
+            type: "string",
+            title: "ActionAsset.accessibility",
+            description:
+              "An optional string that describes the action for screen-readers",
+          },
+        },
+        metaData: {
+          required: false,
+          node: {
+            type: "object",
+            properties: {
+              beacon: {
+                required: false,
+                node: {
+                  name: "BeaconDataType",
+                  source:
+                    "/private/var/tmp/_bazel_kreddy8/6fc13ccb395252816f0c23d8394e8532/sandbox/darwin-sandbox/181/execroot/player/node_modules/@player-ui/beacon-plugin/dist/index.d.ts",
+                  type: "or",
+                  or: [
+                    {
+                      type: "string",
+                      title: "BeaconDataType",
+                    },
+                    {
+                      type: "record",
+                      keyType: {
+                        type: "string",
+                      },
+                      valueType: {
+                        type: "any",
+                      },
+                      title: "BeaconDataType",
+                    },
+                  ],
+                  title: "ActionAsset.metaData.beacon",
+                  description: "Additional data to beacon",
+                },
+              },
+              skipValidation: {
+                required: false,
+                node: {
+                  type: "boolean",
+                  title: "ActionAsset.metaData.skipValidation",
+                  description:
+                    "Force transition to the next view without checking for validation",
+                },
+              },
+            },
+            additionalProperties: false,
+            title: "ActionAsset.metaData",
+            description:
+              "Additional optional data to assist with the action interactions on the page",
+          },
+        },
+      },
+      additionalProperties: false,
+      title: "ActionAsset",
+      description:
+        "User actions can be represented in several places.\nEach view typically has one or more actions that allow the user to navigate away from that view.\nIn addition, several asset types can have actions that apply to that asset only.",
+      genericTokens: [
+        {
+          symbol: "AnyTextAsset",
+          constraints: {
+            type: "ref",
+            ref: "Asset",
+          },
+          default: {
+            type: "ref",
+            ref: "Asset",
+          },
+        },
+      ],
+      extends: {
+        type: "ref",
+        ref: "Asset<'action'>",
+        genericArguments: [
+          {
+            type: "string",
+            const: "action",
+          },
+        ],
+      },
+    } as NamedType;
+
+    const converter = new TSWriter(ts.factory);
+
+    const { type: tsNode, referencedTypes: referencedImports } =
+      converter.convertNamedType(xlr);
+
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const resultFile = ts.createSourceFile(
+      "output.d.ts",
+      "",
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS,
+    );
+
+    const nodeText = printer.printNode(
+      ts.EmitHint.Unspecified,
+      tsNode,
+      resultFile,
+    );
+
+    expect(nodeText).toMatchSnapshot();
+    expect(referencedImports).toMatchInlineSnapshot(`
+      Set {
+        "AssetWrapper",
+        "Expression",
+        "Asset",
+      }
+    `);
+  });
+
+  test("Template Type Conversion", () => {
+    const xlr = {
+      name: "BindingRef",
+      title: "BindingRef",
+      type: "template",
+      format: "{{.*}}",
+    } as NamedType;
+
+    const converter = new TSWriter(ts.factory);
+
+    const { type: tsNode, referencedTypes: referencedImports } =
+      converter.convertNamedType(xlr);
+
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const resultFile = ts.createSourceFile(
+      "output.d.ts",
+      "",
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS,
+    );
+
+    const nodeText = printer.printNode(
+      ts.EmitHint.Unspecified,
+      tsNode,
+      resultFile,
+    );
+
+    expect(nodeText).toMatchSnapshot();
+    expect(referencedImports).toBeUndefined();
+  });
+
+  test("Static Type Conversion Objects", () => {
+    const xlr = {
+      name: "test",
+      source: "test.ts",
+      type: "object",
+      properties: {
+        foo: {
+          required: true,
+          node: {
+            type: "string",
+            const: "foo",
+          },
+        },
+        bar: {
+          required: true,
+          node: {
+            type: "number",
+            const: 1,
+          },
+        },
+        bax: {
+          required: true,
+          node: {
+            type: "boolean",
+            const: false,
+          },
+        },
+      },
+      additionalProperties: false,
+    } as NamedType;
+
+    const converter = new TSWriter(ts.factory);
+
+    const { type: tsNode, referencedTypes: referencedImports } =
+      converter.convertNamedType(xlr);
+
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const resultFile = ts.createSourceFile(
+      "output.d.ts",
+      "",
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS,
+    );
+
+    const nodeText = printer.printNode(
+      ts.EmitHint.Unspecified,
+      tsNode,
+      resultFile,
+    );
+
+    expect(nodeText).toMatchSnapshot();
+    expect(referencedImports).toBeUndefined();
+  });
+
+  test("Static Type Conversion Arrays", () => {
+    const xlr = {
+      name: "test",
+      source: "test.ts",
+      type: "array",
+      elementType: {
+        type: "any",
+      },
+      const: [
+        {
+          type: "string",
+          const: "foo",
+        },
+        {
+          type: "number",
+          const: 1,
+        },
+        {
+          type: "boolean",
+          const: false,
+        },
+      ],
+    } as NamedType;
+
+    const converter = new TSWriter(ts.factory);
+
+    const { type: tsNode, referencedTypes: referencedImports } =
+      converter.convertNamedType(xlr);
+
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const resultFile = ts.createSourceFile(
+      "output.d.ts",
+      "",
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS,
+    );
+
+    const nodeText = printer.printNode(
+      ts.EmitHint.Unspecified,
+      tsNode,
+      resultFile,
+    );
+
+    expect(nodeText).toMatchSnapshot();
+    expect(referencedImports).toBeUndefined();
+  });
+
+  test("Dynamic results Conversion", () => {
+    const xlr = {
+      source: "test.ts",
+      name: "size",
+      type: "ref",
+      ref: "ExpressionHandler",
+      genericArguments: [
+        {
+          type: "tuple",
+          elementTypes: [
+            {
+              name: "val",
+              type: {
+                type: "unknown",
+              },
+            },
+          ],
+          additionalItems: false,
+          minItems: 1,
+        },
+        {
+          type: "number",
+        },
+      ],
+    } as NamedType;
+
+    const converter = new TSWriter(ts.factory);
+
+    const { type: tsNode, referencedTypes: referencedImports } =
+      converter.convertNamedType(xlr);
+
+    const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+    const resultFile = ts.createSourceFile(
+      "output.d.ts",
+      "",
+      ts.ScriptTarget.ES2017,
+      false, // setParentNodes
+      ts.ScriptKind.TS,
+    );
+
+    const nodeText = printer.printNode(
+      ts.EmitHint.Unspecified,
+      tsNode,
+      resultFile,
+    );
+
+    expect(nodeText).toMatchSnapshot();
+    expect(referencedImports).toMatchInlineSnapshot(`
+      Set {
+        "ExpressionHandler",
+      }
+    `);
+  });
+});

package/src/__tests__/documentation.test.ts

@@ -0,0 +1,116 @@
+import { test, expect, describe } from "vitest";
+import type { FunctionType, OrType, TupleType } from "@xlr-lib/xlr";
+import { createDocString } from "../ts/documentation";
+
+describe("docs", () => {
+  test("or", () => {
+    const type1: OrType = {
+      type: "or",
+      or: [
+        {
+          type: "string",
+        },
+        {
+          type: "array",
+          elementType: {
+            type: "string",
+          },
+        },
+      ],
+    };
+
+    expect(createDocString(type1)).toMatchInlineSnapshot(
+      `"string | Array<string>"`,
+    );
+  });
+
+  test("function", () => {
+    const type1: FunctionType = {
+      type: "function",
+      name: "testABC",
+      parameters: [
+        {
+          name: "a",
+          type: {
+            type: "string",
+          },
+        },
+        {
+          name: "b",
+          type: {
+            type: "array",
+            elementType: {
+              type: "string",
+            },
+          },
+        },
+      ],
+      returnType: {
+        type: "string",
+      },
+    };
+
+    expect(createDocString(type1)).toMatchInlineSnapshot(
+      `"function testABC(a: string, b: Array<string>): string"`,
+    );
+  });
+
+  test("tuple", () => {
+    const type1: TupleType = {
+      type: "tuple",
+      name: "testABC",
+      elementTypes: [
+        {
+          name: "a",
+          type: {
+            type: "string",
+          },
+        },
+        {
+          type: {
+            type: "array",
+            elementType: {
+              type: "string",
+            },
+          },
+        },
+      ],
+      minItems: 2,
+      additionalItems: false,
+    };
+
+    expect(createDocString(type1)).toMatchInlineSnapshot(
+      `"[a: string, Array<string>]"`,
+    );
+  });
+
+  test("const", () => {
+    const type1: OrType = {
+      type: "or",
+      or: [
+        {
+          type: "string",
+          const: "abc",
+        },
+        {
+          type: "number",
+          const: 123,
+        },
+        {
+          type: "boolean",
+          const: true,
+        },
+        {
+          type: "array",
+          elementType: {
+            type: "string",
+          },
+        },
+      ],
+    };
+
+    expect(createDocString(type1)).toMatchInlineSnapshot(
+      `""abc" | 123 | true | Array<string>"`,
+    );
+  });
+});

package/src/__tests__/export-to-ts.test.ts

@@ -0,0 +1,68 @@
+import { test, expect, describe } from "vitest";
+import type { NamedType } from "@xlr-lib/xlr";
+import { exportTypesToTypeScript } from "../ts/xlr-to-ts";
+
+const IMPORT_MAP = new Map([["@player-ui/types", ["Asset", "Binding"]]]);
+
+const ASSET_TYPE: NamedType = {
+  name: "Asset",
+  type: "object",
+  source: "test",
+  properties: {
+    id: { required: true, node: { type: "string" } },
+    type: { required: true, node: { type: "string" } },
+  },
+  additionalProperties: false,
+};
+
+const ACTION_ASSET_TYPE: NamedType = {
+  name: "ActionAsset",
+  type: "object",
+  source: "test",
+  properties: {
+    id: { required: true, node: { type: "string" } },
+    type: { required: true, node: { type: "string", const: "action" } },
+    value: { required: false, node: { type: "string" } },
+  },
+  additionalProperties: false,
+};
+
+describe("exportTypesToTypeScript", () => {
+  test("exports named types as a .d.ts string", () => {
+    const result = exportTypesToTypeScript(
+      [ASSET_TYPE, ACTION_ASSET_TYPE],
+      IMPORT_MAP,
+    );
+    expect(typeof result).toBe("string");
+    expect(result).toContain("export interface Asset");
+    expect(result).toContain("export interface ActionAsset");
+    expect(result).toMatchSnapshot();
+  });
+
+  test("emits import declarations for referenced types", () => {
+    const typeWithRef: NamedType = {
+      name: "Wrapper",
+      type: "object",
+      source: "test",
+      properties: {
+        asset: {
+          required: true,
+          node: { type: "ref", ref: "Asset" },
+        },
+      },
+      additionalProperties: false,
+    };
+
+    const result = exportTypesToTypeScript([typeWithRef], IMPORT_MAP);
+    expect(result).toContain("@player-ui/types");
+    expect(result).toContain("Asset");
+    expect(result).toMatchSnapshot();
+  });
+
+  test("skips import declarations for unreferenced packages", () => {
+    const result = exportTypesToTypeScript([ASSET_TYPE], IMPORT_MAP);
+    // Asset itself is defined, not imported — so the import declaration should be absent
+    expect(result).not.toContain("@player-ui/types");
+    expect(result).toMatchSnapshot();
+  });
+});

package/src/__tests__/heritage-additional-properties.test.ts

@@ -0,0 +1,119 @@
+import { test, expect } from "vitest";
+import { setupTestEnv } from "@xlr-lib/test-utils";
+import { TsConverter } from "..";
+
+/**
+ * Tests for handleHeritageClauses: when an interface extends a base that has
+ * no index signature, but the current interface declares [key: string]: unknown,
+ * the merged XLR must include the current interface's additionalProperties
+ * (so the merged type allows extra keys).
+ */
+test("merged type includes current interface additionalProperties when extending base without index signature", () => {
+  const sc = `
+    interface NavigationBaseState {
+      state_type: string;
+      onStart?: string;
+    }
+
+    export interface NavigationFlowEndState extends NavigationBaseState {
+      outcome: string;
+      [key: string]: unknown;
+    }
+  `;
+
+  const { sf, tc } = setupTestEnv(sc);
+  const converter = new TsConverter(tc);
+  const types = converter.convertSourceFile(sf).data.types;
+
+  const endStateType = types.find(
+    (t: { name?: string }) => t.name === "NavigationFlowEndState",
+  );
+  expect(endStateType).toBeDefined();
+  expect(
+    (endStateType as { additionalProperties?: unknown }).additionalProperties,
+  ).not.toBe(false);
+  expect(
+    (
+      (endStateType as { additionalProperties?: { type?: string } })
+        .additionalProperties as { type?: string }
+    )?.type,
+  ).toBe("unknown");
+});
+
+test("merged type includes additionalProperties when only extended type has index signature", () => {
+  const sc = `
+    interface Base {
+      required: string;
+    }
+
+    interface WithIndex {
+      [key: string]: unknown;
+    }
+
+    export interface Child extends Base, WithIndex {
+      extra: number;
+    }
+  `;
+
+  const { sf, tc } = setupTestEnv(sc);
+  const converter = new TsConverter(tc);
+  const types = converter.convertSourceFile(sf).data.types;
+
+  const childType = types.find((t: { name?: string }) => t.name === "Child");
+  expect(childType).toBeDefined();
+  const additionalProperties = (childType as { additionalProperties?: unknown })
+    .additionalProperties;
+  expect(additionalProperties).not.toBe(false);
+  expect((additionalProperties as { type?: string })?.type).toBe("unknown");
+});
+
+test("merged type has no additionalProperties when no interface has index signature", () => {
+  const sc = `
+    interface Base {
+      required: string;
+    }
+
+    export interface Child extends Base {
+      extra: number;
+    }
+  `;
+
+  const { sf, tc } = setupTestEnv(sc);
+  const converter = new TsConverter(tc);
+  const types = converter.convertSourceFile(sf).data.types;
+
+  const childType = types.find((t: { name?: string }) => t.name === "Child");
+  expect(childType).toBeDefined();
+  const additionalProperties = (childType as { additionalProperties?: unknown })
+    .additionalProperties;
+  expect(additionalProperties).toBe(false);
+});
+
+test("merged type combines additionalProperties from current and extended when both have index signatures", () => {
+  const sc = `
+    interface Base {
+      required: string;
+      [key: string]: unknown;
+    }
+
+    export interface Child extends Base {
+      extra: number;
+      [key: string]: unknown;
+    }
+  `;
+
+  const { sf, tc } = setupTestEnv(sc);
+  const converter = new TsConverter(tc);
+  const types = converter.convertSourceFile(sf).data.types;
+
+  const childType = types.find((t: { name?: string }) => t.name === "Child");
+  expect(childType).toBeDefined();
+  const additionalProperties = (childType as { additionalProperties?: unknown })
+    .additionalProperties;
+  expect(additionalProperties).not.toBe(false);
+  // When both have index sigs we merge (e.g. or of both); extra keys are allowed
+  const ap = additionalProperties as { type?: string; or?: unknown[] };
+  expect(
+    ap.type === "unknown" || (ap.type === "or" && Array.isArray(ap.or)),
+  ).toBe(true);
+});