@highstate/cli 0.9.18 → 0.9.20

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"
 
@@ -18,276 +24,240 @@ export const schemaTransformerPlugin: Plugin = {
   },
 }
 
-type Transformation = {
-  start: number
-  end: number
-  newValue: string
-  type: "zod-meta" | "schema-structure" | "import"
+export async function applySchemaTransformations(content: string): Promise<string> {
+  // 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
 }
 
-export async function applySchemaTransformations(content: string): Promise<string> {
+async function applyZodMetaTransformations(content: string): Promise<string> {
   const { program, comments } = await parseAsync("file.ts", content)
-
-  const transformations: Transformation[] = []
   const parentStack: Node[] = []
+  let hasTransformations = false
+  const result = new MagicString(content)
 
   walk(program, {
     enter(node) {
-      parentStack.push(node) // Handle z.object() patterns
-      if (
-        node.type === "Property" &&
-        node.key.type === "Identifier" &&
-        isInsideZodObject(parentStack)
-      ) {
-        const jsdoc = comments.find(comment => isLeadingComment(content, node, comment))
+      parentStack.push(node)
+
+      // handle zod object patterns
+      if (isZodObjectProperty(node, parentStack)) {
+        const jsdoc = findLeadingComment(content, node, comments)
         if (jsdoc) {
           const description = cleanJsdoc(jsdoc.value)
-          const fieldName = node.key.name
+          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)
 
-          // Check if the field already has .meta() call
           if (!originalValue.includes(".meta(")) {
-            transformations.push({
-              start: node.value.start,
-              end: node.value.end,
-              newValue: `${originalValue}.meta({ title: __camelCaseToHumanReadable("${fieldName}"), description: \`${description}\` })`,
-              type: "zod-meta",
-            })
+            const newValue = `${originalValue}.meta({ title: __camelCaseToHumanReadable("${fieldName}"), description: \`${description}\` })`
+            result.update(node.value.start, node.value.end, newValue)
+            hasTransformations = true
           }
         }
-        return
-      }
-
-      if (node.type !== "Property" || node.key.type !== "Identifier") {
-        return
-      }
-
-      const parentKey = getParentObjectKey(parentStack) || getMarkerFunctionName(parentStack)
-      if (!parentKey || !["inputs", "outputs", "args", "secrets"].includes(parentKey)) {
-        return
-      }
-
-      const jsdoc = comments.find(comment => isLeadingComment(content, node, comment))
-      if (!jsdoc) {
-        return
-      }
-
-      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)
-        transformations.push({
-          start: node.value.start,
-          end: node.value.end,
-          newValue: modifiedValue,
-          type: "schema-structure",
-        })
-      } else {
-        // Transform to new structure
-        transformations.push({
-          start: node.value.start,
-          end: node.value.end,
-          newValue: `{
-  ${entityField}: ${originalValue},
-  meta: {
-    description: \`${description}\`,
-  },
-}`,
-          type: "schema-structure",
-        })
       }
     },
     leave() {
       parentStack.pop()
     },
-  }) // Handle overlapping transformations by merging them
-  const zodMetaTransformations = transformations.filter(t => t.type === "zod-meta")
-  const schemaTransformations = transformations.filter(t => t.type === "schema-structure")
-
-  // For each schema transformation, check if it contains zod-meta transformations
-  const processedSchemaTransformations = schemaTransformations.map(schemaTransform => {
-    const containedZodMetas = zodMetaTransformations.filter(zodTransform => {
-      return schemaTransform.start <= zodTransform.start && schemaTransform.end >= zodTransform.end
-    })
-
-    if (containedZodMetas.length > 0) {
-      // Apply the zod-meta transformations to the original content first
-      const originalContent = content.substring(schemaTransform.start, schemaTransform.end)
-      const tempMagicString = new MagicString(originalContent)
-
-      // Adjust positions relative to the schema transformation start
-      containedZodMetas
-        .sort((a, b) => b.start - a.start)
-        .forEach(zodTransform => {
-          const relativeStart = zodTransform.start - schemaTransform.start
-          const relativeEnd = zodTransform.end - schemaTransform.start
-          tempMagicString.update(relativeStart, relativeEnd, zodTransform.newValue)
-        })
-
-      const modifiedContent = tempMagicString.toString()
-
-      // Now create the schema transformation with the modified content
-      const entityField = schemaTransform.newValue.includes("entity:") ? "entity" : "schema"
-      const descriptionMatch = schemaTransform.newValue.match(/description: `([^`]+)`/)
-
-      if (descriptionMatch) {
-        const description = descriptionMatch[1]
-
-        // Check if the original content is already structured
-        const isAlreadyStructured = isStructuredValue(
-          content.substring(schemaTransform.start, schemaTransform.end),
-          entityField,
-        )
-
-        if (isAlreadyStructured) {
-          // Just inject the description into the existing structure with modified content
-          return {
-            ...schemaTransform,
-            newValue: injectDescriptionIntoObject(modifiedContent, description),
-            containsZodMeta: true,
-          }
-        } else {
-          // Create new structure with modified content
-          return {
-            ...schemaTransform,
-            newValue: `{
-  ${entityField}: ${modifiedContent},
-  meta: {
-    description: \`${description}\`,
-  },
-}`,
-            containsZodMeta: true,
-          }
-        }
-      }
-    }
-
-    return { ...schemaTransform, containsZodMeta: false }
   })
 
-  // Filter out zod-meta transformations that are already included in schema transformations
-  const independentZodMetas = zodMetaTransformations.filter(zodTransform => {
-    return !schemaTransformations.some(schemaTransform => {
-      return schemaTransform.start <= zodTransform.start && schemaTransform.end >= zodTransform.end
-    })
-  })
+  let finalResult = result.toString()
 
-  // Combine the transformations
-  const finalTransformations = [
-    ...independentZodMetas,
-    ...processedSchemaTransformations.map(({ containsZodMeta, ...rest }) => rest), // eslint-disable-line @typescript-eslint/no-unused-vars
-  ]
+  // add import at the beginning if needed
+  if (hasTransformations && !content.includes("__camelCaseToHumanReadable")) {
+    finalResult =
+      'import { camelCaseToHumanReadable as __camelCaseToHumanReadable } from "@highstate/contract"\n' +
+      finalResult
+  }
 
-  // Check if we need to add the import for camelCaseToHumanReadable
-  const hasZodMetaTransformations = zodMetaTransformations.length > 0
-  const needsImport = hasZodMetaTransformations && !content.includes("__camelCaseToHumanReadable")
+  return finalResult
+}
 
-  let result = content
-  const magicString = new MagicString(result)
+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)
 
-  // Apply all transformations
-  finalTransformations
-    .sort((a, b) => b.start - a.start) // Sort in reverse order by start position
-    .forEach(transformation => {
-      magicString.update(transformation.start, transformation.end, transformation.newValue)
-    })
+  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() {
+      parentStack.pop()
+    },
+  })
 
-  result = magicString.toString()
+  let finalResult = result.toString()
 
-  // Add import at the beginning if needed
-  if (needsImport) {
-    result =
-      'import { camelCaseToHumanReadable as __camelCaseToHumanReadable } from "@highstate/contract"\n' +
-      result
+  // add import at the beginning if needed
+  if (hasTransformations && !content.includes("$addArgumentDescription")) {
+    finalResult =
+      'import { $addArgumentDescription, $addInputDescription } from "@highstate/contract"\n' +
+      finalResult
   }
 
-  return result
+  return finalResult
 }
 
-function injectDescriptionIntoObject(objectString: string, description: string): string {
-  const trimmed = objectString.trim()
-
-  // Check if the object already has a meta field
-  const metaRegex = /meta\s*:\s*\{/
-
-  if (metaRegex.test(trimmed)) {
-    // Check if the meta field already has a description
-    const hasDescription = /meta\s*:\s*\{[^}]*description\s*:/.test(trimmed)
-
-    if (hasDescription) {
-      // Replace existing description
-      return trimmed.replace(/description\s*:\s*`[^`]*`/, `description: \`${description}\``)
-    } else {
-      // Add description at the beginning of the meta object
-      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
-    }
-
-    const beforeBrace = trimmed.substring(0, lastBraceIndex)
-    const afterBrace = trimmed.substring(lastBraceIndex)
+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 we need a comma before adding meta
-    const needsComma = beforeBrace.trim().length > 1 && !beforeBrace.trim().endsWith(",")
-    const comma = needsComma ? "," : ""
+  walk(program, {
+    enter(node) {
+      parentStack.push(node)
+
+      // 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]
+
+            // 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
+
+              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
     }
   }
@@ -318,12 +288,37 @@ function cleanJsdoc(str: string) {
   )
 }
 
+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
+  // 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)
     ) {
@@ -334,52 +329,63 @@ function isInsideZodObject(parentStack: Node[]): boolean {
 }
 
 function isZodObjectCall(memberExpression: Node): boolean {
-  if (memberExpression.type !== "MemberExpression") {
+  if (
+    memberExpression.type !== "MemberExpression" ||
+    !("object" in memberExpression) ||
+    !("property" in memberExpression)
+  ) {
     return false
   }
 
-  // Handle direct z.object() calls
+  const member = memberExpression as MemberExpression
+
+  // handle direct z.object() calls
   if (
-    memberExpression.object.type === "Identifier" &&
-    memberExpression.object.name === "z" &&
-    memberExpression.property.type === "Identifier" &&
-    memberExpression.property.name === "object"
+    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()
+  // handle chained calls like z.discriminatedUnion().default().object()
   // or any other chained Zod methods that end with .object()
   if (
-    memberExpression.property.type === "Identifier" &&
-    memberExpression.property.name === "object" &&
-    memberExpression.object.type === "CallExpression" &&
-    memberExpression.object.callee.type === "MemberExpression"
+    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(memberExpression.object)
+    // recursively check if this is part of a z.* chain
+    return startsWithZodCall(member.object)
   }
 
   return false
 }
 
-function startsWithZodCall(callExpression: Node): boolean {
+function startsWithZodCall(callExpression: CallExpression): boolean {
   if (!callExpression || callExpression.type !== "CallExpression") {
     return false
   }
 
   if (callExpression.callee.type === "MemberExpression") {
-    // Check if this is a direct z.* call
+    const callee = callExpression.callee
+
+    // check if this is a direct z.* call
     if (
-      callExpression.callee.object.type === "Identifier" &&
-      callExpression.callee.object.name === "z"
+      callee.object.type === "Identifier" &&
+      "name" in callee.object &&
+      callee.object.name === "z"
     ) {
       return true
     }
 
-    // Recursively check nested calls
-    if (callExpression.callee.object.type === "CallExpression") {
-      return startsWithZodCall(callExpression.callee.object)
+    // recursively check nested calls
+    if (callee.object.type === "CallExpression") {
+      return startsWithZodCall(callee.object)
     }
   }
 

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

@@ -136,7 +136,6 @@ export class SourceHashCalculator {
             }),
           )
           break
-        case "auto":
         default:
           promises.push(
             this.getFileHash(fullPath).then(hash => ({