@highstate/cli 0.9.18 → 0.9.20

package/src/shared/schema-transformer.spec.ts

@@ -2,7 +2,7 @@ import { describe, it, expect } from "vitest"
 import { applySchemaTransformations } from "./schema-transformer"
 
 describe("applySchemaTransformations", () => {
-  it("should transform simple values to entity/schema structure", async () => {
+  it("should transform simple values using helper functions", async () => {
     const input = `
 const spec = {
   inputs: {
@@ -21,13 +21,16 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: clusterEntity")
-    expect(result).toContain("schema: Type.Number()")
-    expect(result).toContain("description: `The Kubernetes cluster to deploy on.`")
-    expect(result).toContain("description: `The port number to use.`")
+    expect(result).toContain(
+      "$addInputDescription(clusterEntity, `The Kubernetes cluster to deploy on.`)",
+    )
+    expect(result).toContain("$addArgumentDescription(Type.Number(), `The port number to use.`)")
+    expect(result).toContain(
+      'import { $addArgumentDescription, $addInputDescription } from "@highstate/contract"',
+    )
   })
 
-  it("should inject description into existing meta field", async () => {
+  it("should wrap existing structured objects with helper functions", async () => {
     const input = `
 const spec = {
   args: {
@@ -46,14 +49,13 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
+    expect(result).toContain("$addArgumentDescription({")
     expect(result).toContain('displayName: "API Token"')
     expect(result).toContain("sensitive: true")
-    expect(result).toContain("description: `The API token for authentication.`")
-    expect(result).not.toContain("...obj")
-    expect(result).not.toContain("((obj) =>")
+    expect(result).toContain("}, `The API token for authentication.`)")
   })
 
-  it("should add meta field if it doesn't exist in structured object", async () => {
+  it("should wrap structured objects with helper functions", async () => {
     const input = `
 const spec = {
   inputs: {
@@ -69,10 +71,10 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
+    expect(result).toContain("$addInputDescription({")
     expect(result).toContain("entity: endpointEntity")
     expect(result).toContain("required: false")
-    expect(result).toContain("meta: {")
-    expect(result).toContain("description: `The target endpoint.`")
+    expect(result).toContain("}, `The target endpoint.`)")
   })
 
   it("should handle $args marker function", async () => {
@@ -88,8 +90,9 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
-    expect(result).toContain("description: `The configuration file path.`")
+    expect(result).toContain(
+      "$addArgumentDescription(Type.String(), `The configuration file path.`)",
+    )
   })
 
   it("should handle $inputs marker function", async () => {
@@ -105,8 +108,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: dataEntity")
-    expect(result).toContain("description: `The source data.`")
+    expect(result).toContain("$addInputDescription(dataEntity, `The source data.`)")
   })
 
   it("should handle $outputs marker function", async () => {
@@ -122,8 +124,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("entity: resultEntity")
-    expect(result).toContain("description: `The processed result.`")
+    expect(result).toContain("$addInputDescription(resultEntity, `The processed result.`)")
   })
 
   it("should handle $secrets marker function", async () => {
@@ -139,8 +140,7 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
-    expect(result).toContain("description: `The database password.`")
+    expect(result).toContain("$addArgumentDescription(Type.String(), `The database password.`)")
   })
 
   it("should ignore properties without JSDoc comments", async () => {
@@ -158,8 +158,7 @@ const spec = {
     const result = await applySchemaTransformations(input)
 
     expect(result).toContain("cluster: clusterEntity") // unchanged
-    expect(result).toContain("entity: endpointEntity") // transformed
-    expect(result).toContain("description: `Only this one has a comment.`")
+    expect(result).toContain("$addInputDescription(endpointEntity, `Only this one has a comment.`)") // transformed
   })
 
   it("should ignore properties not in target objects", async () => {
@@ -183,7 +182,7 @@ const spec = {
     const result = await applySchemaTransformations(input)
 
     expect(result).toContain('someProperty: "value"') // unchanged
-    expect(result).toContain("entity: clusterEntity") // transformed
+    expect(result).toContain("$addInputDescription(clusterEntity, `This should be transformed.`)") // transformed
   })
 
   it("should clean JSDoc comments properly", async () => {
@@ -200,11 +199,10 @@ const spec = {
 
     const result = await applySchemaTransformations(input)
 
-    expect(result).toContain("schema: Type.String()")
     expect(result).toContain(
-      "description: `This is a description with \\`backticks\\` and \\${template} literals.",
+      "$addArgumentDescription(Type.String(), `This is a description with \\`backticks\\` and \\${template} literals.",
     )
-    expect(result).toContain("It also has multiple lines.`")
+    expect(result).toContain("It also has multiple lines.`)")
   })
 
   it("should add .meta() to z.object fields with JSDoc comments", async () => {
@@ -445,13 +443,10 @@ var virtualMachine = defineUnit({
 
     const result = await applySchemaTransformations(input)
 
-    // Should transform args.ipv4 to entity/schema structure (existing transformer behavior)
-    expect(result).toContain("ipv4: {")
+    // Should transform args.ipv4 using $addArgumentDescription helper
+    expect(result).toContain("ipv4: $addArgumentDescription({")
     expect(result).toContain("schema: z.discriminatedUnion")
-    expect(result).toContain("meta: {")
-    expect(result).toContain(
-      "description: `The IPv4 address configuration for the virtual machine.`",
-    )
+    expect(result).toContain("}, `The IPv4 address configuration for the virtual machine.`)")
 
     // Should add .meta() to z.object fields with JSDoc comments inside the discriminated union
     expect(result).toContain(
@@ -476,14 +471,162 @@ var virtualMachine = defineUnit({
     expect(result).toContain('type: z.literal("dhcp")') // unchanged
     expect(result).toContain('type: z.literal("static"),') // unchanged
 
-    // Should properly handle inputs.vendorData with existing meta (no change expected since it already has meta)
-    expect(result).toContain("vendorData: {")
+    // Should properly handle inputs.vendorData using $addInputDescription helper
+    expect(result).toContain("vendorData: $addInputDescription({")
     expect(result).toContain("entity: fileEntity,")
     expect(result).toContain("required: false,")
-    expect(result).toContain("You can provide a cloud-config from the distribution component.")
+    expect(result).toContain("}, `The cloud-init vendor data to use for the virtual machine.")
+    expect(result).toContain("You can provide a cloud-config from the distribution component.`)")
 
     // Should NOT transform other inputs without JSDoc
     expect(result).toContain("proxmoxCluster: clusterEntity,") // unchanged
     expect(result).toContain("image: imageEntity,") // unchanged
   })
+
+  it("should add description to defineUnit function with JSDoc", async () => {
+    const input = `
+/**
+ * Installs the Gateway API CRDs to the cluster.
+ */
+export const gatewayApi = defineUnit({
+  type: "k8s.gateway-api",
+  inputs: {
+    k8sCluster: clusterEntity,
+  },
+  outputs: {
+    k8sCluster: clusterEntity,
+  },
+  meta: {
+    title: "Gateway API",
+    icon: "devicon:kubernetes",
+    secondaryIcon: "mdi:api",
+    secondaryIconColor: "#4CAF50",
+    category: "Kubernetes",
+  },
+  source: {
+    package: "@highstate/k8s",
+    path: "units/gateway-api",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `Installs the Gateway API CRDs to the cluster.`")
+    expect(result).toContain('title: "Gateway API"')
+    expect(result).toContain('icon: "devicon:kubernetes"')
+  })
+
+  it("should add meta field to defineEntity without existing meta", async () => {
+    const input = `
+/**
+ * Represents a Kubernetes cluster.
+ */
+export const clusterEntity = defineEntity({
+  type: "k8s.cluster",
+  schema: z.object({
+    name: z.string(),
+    endpoint: z.string(),
+  }),
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("meta: {")
+    expect(result).toContain("description: `Represents a Kubernetes cluster.`")
+    expect(result).toContain("schema: z.object({")
+  })
+
+  it("should add description to defineComponent function", async () => {
+    const input = `
+/**
+ * A reusable database component.
+ */
+export const database = defineComponent({
+  type: "database",
+  components: {
+    server: serverUnit,
+    storage: storageUnit,
+  },
+  meta: {
+    category: "Database",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `A reusable database component.`")
+    expect(result).toContain('category: "Database"')
+  })
+
+  it("should not transform define functions without JSDoc", async () => {
+    const input = `
+export const simpleUnit = defineUnit({
+  type: "simple",
+  meta: {
+    title: "Simple Unit",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).not.toContain("description:")
+    expect(result).toContain('title: "Simple Unit"')
+  })
+
+  it("should not create nested meta.meta.description structure", async () => {
+    const input = `
+/**
+ * Traefik Gateway unit definition for Kubernetes.
+ */
+var traefikGateway = defineUnit({
+  type: "k8s.apps.traefik-gateway.v1",
+  meta: {
+    title: "Traefik Gateway",
+    icon: "simple-icons:traefikproxy",
+    category: "Network",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    // Should have description at the correct level
+    expect(result).toContain("meta: {")
+    expect(result).toContain("description: `Traefik Gateway unit definition for Kubernetes.`")
+    expect(result).toContain('title: "Traefik Gateway"')
+    expect(result).toContain('icon: "simple-icons:traefikproxy"')
+    expect(result).toContain('category: "Network"')
+
+    // Should NOT have nested meta.meta structure
+    expect(result).not.toContain("meta: {\\s*meta: {")
+
+    // Verify the structure more precisely - should only have one meta object
+    const metaMatches = (result.match(/meta\s*:\s*\{/g) || []).length
+    expect(metaMatches).toBe(1)
+  })
+
+  it("should replace existing description in defineUnit meta object", async () => {
+    const input = `
+/**
+ * Updated description for the unit.
+ */
+export const testUnit = defineUnit({
+  type: "test",
+  meta: {
+    title: "Test Unit",
+    description: \`Old description.\`,
+    category: "Test",
+  },
+})`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("description: `Updated description for the unit.`")
+    expect(result).not.toContain("Old description")
+    expect(result).toContain('title: "Test Unit"')
+    expect(result).toContain('category: "Test"')
+
+    // Should still only have one meta object
+    const metaMatches = (result.match(/meta\s*:\s*\{/g) || []).length
+    expect(metaMatches).toBe(1)
+  })
 })