@highstate/cli 0.9.16 → 0.9.19

package/src/shared/schema-transformer.ts

@@ -1,6 +1,12 @@
 import type { Plugin } from "esbuild"
 import { readFile } from "node:fs/promises"
-import { parseAsync, type Comment } from "oxc-parser"
+import {
+  parseAsync,
+  type Comment,
+  type CallExpression,
+  type ObjectProperty,
+  type MemberExpression,
+} from "oxc-parser"
 import { walk, type Node } from "oxc-walker"
 import MagicString from "magic-string"
 
@@ -19,53 +25,99 @@ export const schemaTransformerPlugin: Plugin = {
 }
 
 export async function applySchemaTransformations(content: string): Promise<string> {
-  const magicString = new MagicString(content)
-  const { program, comments } = await parseAsync("file.ts", content)
+  // first pass: apply zod meta transformations
+  let result = await applyZodMetaTransformations(content)
+
+  // second pass: apply helper function transformations
+  result = await applyHelperFunctionTransformations(result)
 
+  // third pass: apply define function meta transformations
+  result = await applyDefineFunctionMetaTransformations(result)
+
+  return result
+}
+
+async function applyZodMetaTransformations(content: string): Promise<string> {
+  const { program, comments } = await parseAsync("file.ts", content)
   const parentStack: Node[] = []
+  let hasTransformations = false
+  const result = new MagicString(content)
 
   walk(program, {
     enter(node) {
       parentStack.push(node)
 
-      if (node.type !== "Property" || node.key.type !== "Identifier") {
-        return
-      }
+      // handle zod object patterns
+      if (isZodObjectProperty(node, parentStack)) {
+        const jsdoc = findLeadingComment(content, node, comments)
+        if (jsdoc) {
+          const description = cleanJsdoc(jsdoc.value)
+          const fieldName =
+            "name" in node.key && typeof node.key.name === "string" ? node.key.name : "unknown"
+          const originalValue = content.substring(node.value.start, node.value.end)
 
-      const parentKey = getParentObjectKey(parentStack) || getMarkerFunctionName(parentStack)
-      if (!parentKey || !["inputs", "outputs", "args", "secrets"].includes(parentKey)) {
-        return
+          if (!originalValue.includes(".meta(")) {
+            const newValue = `${originalValue}.meta({ title: __camelCaseToHumanReadable("${fieldName}"), description: \`${description}\` })`
+            result.update(node.value.start, node.value.end, newValue)
+            hasTransformations = true
+          }
+        }
       }
+    },
+    leave() {
+      parentStack.pop()
+    },
+  })
 
-      const jsdoc = comments.find(comment => isLeadingComment(content, node, comment))
-      if (!jsdoc) {
-        return
-      }
+  let finalResult = result.toString()
 
-      const description = cleanJsdoc(jsdoc.value)
-      const originalValue = content.substring(node.value.start, node.value.end)
-
-      const entityField = ["inputs", "outputs"].includes(parentKey) ? "entity" : "schema"
-
-      // Check if the value already has entity/schema structure
-      const isAlreadyStructured = isStructuredValue(originalValue, entityField)
-
-      if (isAlreadyStructured) {
-        // For already structured values, inject description directly into the object
-        const modifiedValue = injectDescriptionIntoObject(originalValue, description)
-        magicString.update(node.value.start, node.value.end, modifiedValue)
-      } else {
-        // Transform to new structure
-        magicString.update(
-          node.value.start,
-          node.value.end,
-          `{
-  ${entityField}: ${originalValue},
-  meta: {
-    description: \`${description}\`,
-  },
-}`,
-        )
+  // add import at the beginning if needed
+  if (hasTransformations && !content.includes("__camelCaseToHumanReadable")) {
+    finalResult =
+      'import { camelCaseToHumanReadable as __camelCaseToHumanReadable } from "@highstate/contract"\n' +
+      finalResult
+  }
+
+  return finalResult
+}
+
+async function applyHelperFunctionTransformations(content: string): Promise<string> {
+  const { program, comments } = await parseAsync("file.ts", content)
+  const parentStack: Node[] = []
+  let hasTransformations = false
+  const result = new MagicString(content)
+
+  walk(program, {
+    enter(node) {
+      parentStack.push(node)
+
+      // handle properties in args, inputs, outputs, secrets objects
+      if (node.type === "Property" && "key" in node && node.key?.type === "Identifier") {
+        const propertyNode = node
+        const parentKey = getParentObjectKey(parentStack)
+
+        if (parentKey && ["inputs", "outputs", "args", "secrets"].includes(parentKey)) {
+          const jsdoc = findLeadingComment(content, node, comments)
+
+          if (jsdoc) {
+            const description = cleanJsdoc(jsdoc.value)
+            const originalValue = content.substring(
+              propertyNode.value.start,
+              propertyNode.value.end,
+            )
+
+            let helperFunction: string
+            if (["args", "secrets"].includes(parentKey)) {
+              helperFunction = "$addArgumentDescription"
+            } else {
+              helperFunction = "$addInputDescription"
+            }
+
+            const newValue = `${helperFunction}(${originalValue}, \`${description}\`)`
+            result.update(propertyNode.value.start, propertyNode.value.end, newValue)
+            hasTransformations = true
+          }
+        }
       }
     },
     leave() {
@@ -73,78 +125,139 @@ export async function applySchemaTransformations(content: string): Promise<strin
     },
   })
 
-  return magicString.toString()
+  let finalResult = result.toString()
+
+  // add import at the beginning if needed
+  if (hasTransformations && !content.includes("$addArgumentDescription")) {
+    finalResult =
+      'import { $addArgumentDescription, $addInputDescription } from "@highstate/contract"\n' +
+      finalResult
+  }
+
+  return finalResult
 }
 
-function injectDescriptionIntoObject(objectString: string, description: string): string {
-  const trimmed = objectString.trim()
+async function applyDefineFunctionMetaTransformations(content: string): Promise<string> {
+  const { program, comments } = await parseAsync("file.ts", content)
+  const parentStack: Node[] = []
+  const result = new MagicString(content)
 
-  // Check if the object already has a meta field
-  const metaRegex = /meta\s*:\s*\{/
+  walk(program, {
+    enter(node) {
+      parentStack.push(node)
 
-  if (metaRegex.test(trimmed)) {
-    // Find the meta field and inject description into it
-    return trimmed.replace(
-      /meta\s*:\s*\{/,
-      `meta: {
-    description: \`${description}\`,`,
-    )
-  } else {
-    // Add meta field at the end of the object (before the closing brace)
-    const lastBraceIndex = trimmed.lastIndexOf("}")
-    if (lastBraceIndex === -1) {
-      // Invalid object structure, return as is
-      return trimmed
-    }
+      // handle defineUnit, defineEntity, defineComponent function calls
+      if (node.type === "CallExpression" && "callee" in node && node.callee.type === "Identifier") {
+        const callNode = node
+        const callee = callNode.callee
+        const functionName =
+          "name" in callee && typeof callee.name === "string" ? callee.name : undefined
+
+        if (
+          functionName &&
+          ["defineUnit", "defineEntity", "defineComponent"].includes(functionName)
+        ) {
+          // look for JSDoc comment on the parent declaration/export, not the function call itself
+          const jsdoc = findJsdocForDefineFunction(content, parentStack, comments)
+
+          if (jsdoc && callNode.arguments && callNode.arguments.length > 0) {
+            const description = cleanJsdoc(jsdoc.value)
+            const firstArg = callNode.arguments[0]
 
-    const beforeBrace = trimmed.substring(0, lastBraceIndex)
-    const afterBrace = trimmed.substring(lastBraceIndex)
+            // find meta property in the object expression
+            if (firstArg.type === "ObjectExpression" && "properties" in firstArg) {
+              const properties = firstArg.properties
+              const metaProperty = properties?.find(
+                prop =>
+                  prop.type === "Property" &&
+                  "key" in prop &&
+                  prop.key?.type === "Identifier" &&
+                  prop.key?.name === "meta",
+              ) as ObjectProperty | undefined
 
-    // Check if we need a comma before adding meta
-    const needsComma = beforeBrace.trim().length > 1 && !beforeBrace.trim().endsWith(",")
-    const comma = needsComma ? "," : ""
+              if (metaProperty && "value" in metaProperty) {
+                // inject description into existing meta object
+                const originalMetaValue = content.substring(
+                  metaProperty.value.start,
+                  metaProperty.value.end,
+                )
+                const newMetaValue = injectDescriptionIntoMetaObject(originalMetaValue, description)
+                result.update(metaProperty.value.start, metaProperty.value.end, newMetaValue)
+              } else if (properties && properties.length > 0) {
+                // add meta property with description
+                const lastProperty = properties[properties.length - 1] as ObjectProperty
+                if (lastProperty && "end" in lastProperty) {
+                  const insertPos = lastProperty.end
+                  const newMetaProperty = `,
 
-    return `${beforeBrace}${comma}
   meta: {
     description: \`${description}\`,
-  },
-${afterBrace}`
-  }
-}
-
-function isStructuredValue(value: string, expectedField: string): boolean {
-  const trimmed = value.trim()
-  if (!trimmed.startsWith("{")) {
-    return false
-  }
+  }`
+                  result.appendLeft(insertPos, newMetaProperty)
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    leave() {
+      parentStack.pop()
+    },
+  })
 
-  // Check if it contains the expected field (entity or schema) at the top level
-  const fieldPattern = new RegExp(`^\\s*{[^}]*\\b${expectedField}\\s*:`, "s")
-  return fieldPattern.test(trimmed)
+  return result.toString()
 }
 
-function getMarkerFunctionName(parentStack: Node[]): string | null {
-  // Look for marker functions like $args, $inputs, $outputs, $secrets
+function findJsdocForDefineFunction(
+  content: string,
+  parentStack: Node[],
+  comments: Comment[],
+): Comment | null {
+  // look for the variable declaration or export declaration that contains the function call
   for (let i = parentStack.length - 1; i >= 0; i--) {
     const node = parentStack[i]
-    if (node.type === "CallExpression" && node.callee.type === "Identifier") {
-      const functionName = node.callee.name
-      if (
-        functionName.startsWith("$") &&
-        ["$args", "$inputs", "$outputs", "$secrets"].includes(functionName)
-      ) {
-        return functionName.substring(1) // Remove the $ prefix
-      }
+
+    // check for variable declaration (const x = defineUnit(...))
+    if (node.type === "VariableDeclarator" && "id" in node && node.id?.type === "Identifier") {
+      const jsdoc = findLeadingComment(content, node, comments)
+      if (jsdoc) return jsdoc
+    }
+
+    // check for export variable declaration (export const x = defineUnit(...))
+    if (node.type === "VariableDeclaration") {
+      const jsdoc = findLeadingComment(content, node, comments)
+      if (jsdoc) return jsdoc
+    }
+
+    // check for export declaration (export const x = ...)
+    if (node.type === "ExportNamedDeclaration" && "declaration" in node && node.declaration) {
+      const jsdoc = findLeadingComment(content, node, comments)
+      if (jsdoc) return jsdoc
     }
   }
+
   return null
 }
 
+function isZodObjectProperty(node: Node, parentStack: Node[]): node is ObjectProperty {
+  return (
+    node.type === "Property" &&
+    "key" in node &&
+    node.key?.type === "Identifier" &&
+    isInsideZodObject(parentStack)
+  )
+}
+
+function findLeadingComment(content: string, node: Node, comments: Comment[]): Comment | null {
+  return comments.find(comment => isLeadingComment(content, node, comment)) ?? null
+}
+
 function getParentObjectKey(parentStack: Node[]): string | null {
-  // Walk up the parent stack to find the parent object property
+  // walk up the parent stack to find the parent object property
   for (let i = parentStack.length - 2; i >= 0; i--) {
     const node = parentStack[i]
-    if (node.type === "Property" && node.key.type === "Identifier") {
+    if (node.type === "Property" && "key" in node && node.key.type === "Identifier") {
       return node.key.name
     }
   }
@@ -174,3 +287,107 @@ function cleanJsdoc(str: string) {
       .trim()
   )
 }
+
+function injectDescriptionIntoMetaObject(objectString: string, description: string): string {
+  const trimmed = objectString.trim()
+
+  // Check if description already exists
+  const hasDescription = /description\s*:/.test(trimmed)
+
+  if (hasDescription) {
+    // Replace existing description
+    return trimmed.replace(/description\s*:\s*`[^`]*`/, `description: \`${description}\``)
+  } else {
+    // Add description field at the beginning of the object
+    const openBraceIndex = trimmed.indexOf("{")
+    if (openBraceIndex === -1) {
+      return trimmed
+    }
+
+    const beforeBrace = trimmed.substring(0, openBraceIndex + 1)
+    const afterBrace = trimmed.substring(openBraceIndex + 1)
+
+    return `${beforeBrace}
+    description: \`${description}\`,${afterBrace}`
+  }
+}
+
+function isInsideZodObject(parentStack: Node[]): boolean {
+  // look for z.object() call expression in the parent stack
+  for (let i = parentStack.length - 1; i >= 0; i--) {
+    const node = parentStack[i]
+    if (
+      node.type === "CallExpression" &&
+      "callee" in node &&
+      node.callee.type === "MemberExpression" &&
+      isZodObjectCall(node.callee)
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+function isZodObjectCall(memberExpression: Node): boolean {
+  if (
+    memberExpression.type !== "MemberExpression" ||
+    !("object" in memberExpression) ||
+    !("property" in memberExpression)
+  ) {
+    return false
+  }
+
+  const member = memberExpression as MemberExpression
+
+  // handle direct z.object() calls
+  if (
+    member.object.type === "Identifier" &&
+    "name" in member.object &&
+    member.object.name === "z" &&
+    member.property.type === "Identifier" &&
+    member.property.name === "object"
+  ) {
+    return true
+  }
+
+  // handle chained calls like z.discriminatedUnion().default().object()
+  // or any other chained Zod methods that end with .object()
+  if (
+    member.property.type === "Identifier" &&
+    member.property.name === "object" &&
+    member.object.type === "CallExpression" &&
+    "callee" in member.object &&
+    member.object.callee.type === "MemberExpression"
+  ) {
+    // recursively check if this is part of a z.* chain
+    return startsWithZodCall(member.object)
+  }
+
+  return false
+}
+
+function startsWithZodCall(callExpression: CallExpression): boolean {
+  if (!callExpression || callExpression.type !== "CallExpression") {
+    return false
+  }
+
+  if (callExpression.callee.type === "MemberExpression") {
+    const callee = callExpression.callee
+
+    // check if this is a direct z.* call
+    if (
+      callee.object.type === "Identifier" &&
+      "name" in callee.object &&
+      callee.object.name === "z"
+    ) {
+      return true
+    }
+
+    // recursively check nested calls
+    if (callee.object.type === "CallExpression") {
+      return startsWithZodCall(callee.object)
+    }
+  }
+
+  return false
+}

package/src/shared/source-hash-calculator.ts

@@ -6,7 +6,6 @@ import { readPackageJSON, resolvePackageJSON, type PackageJson } from "pkg-types
 import { crc32 } from "@aws-crypto/crc32"
 import { resolve as importMetaResolve } from "import-meta-resolve"
 import { z } from "zod"
-import { int32ToBytes } from "@highstate/backend/shared"
 import {
   type HighstateManifest,
   type HighstateConfig,
@@ -15,6 +14,7 @@ import {
   highstateManifestSchema,
   sourceHashConfigSchema,
 } from "./schemas"
+import { int32ToBytes } from "./utils"
 
 type FileDependency =
   | {
@@ -136,7 +136,6 @@ export class SourceHashCalculator {
             }),
           )
           break
-        case "auto":
         default:
           promises.push(
             this.getFileHash(fullPath).then(hash => ({

package/src/shared/utils.ts

@@ -0,0 +1,6 @@
+export function int32ToBytes(value: number): Uint8Array {
+  const buffer = new ArrayBuffer(4)
+  const view = new DataView(buffer)
+  view.setInt32(0, value, true) // true for little-endian
+  return new Uint8Array(buffer)
+}