@highstate/cli 0.9.15 → 0.9.18

package/src/shared/schema-transformer.ts

@@ -18,33 +18,280 @@ 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> {
-  const magicString = new MagicString(content)
   const { program, comments } = await parseAsync("file.ts", content)
 
+  const transformations: Transformation[] = []
+  const parentStack: Node[] = []
+
   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))
+        if (jsdoc) {
+          const description = cleanJsdoc(jsdoc.value)
+          const fieldName = node.key.name
+          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",
+            })
+          }
+        }
+        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 || !jsdoc.value.includes("@schema")) {
+      if (!jsdoc) {
         return
       }
 
-      magicString.update(
-        node.value.start,
-        node.value.end,
-        `{
-  ...${content.substring(node.value.start, node.value.end)},
-  description: \`${cleanJsdoc(jsdoc.value)}\`,
+      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
+    })
   })
 
-  return magicString.toString()
+  // Combine the transformations
+  const finalTransformations = [
+    ...independentZodMetas,
+    ...processedSchemaTransformations.map(({ containsZodMeta, ...rest }) => rest), // eslint-disable-line @typescript-eslint/no-unused-vars
+  ]
+
+  // Check if we need to add the import for camelCaseToHumanReadable
+  const hasZodMetaTransformations = zodMetaTransformations.length > 0
+  const needsImport = hasZodMetaTransformations && !content.includes("__camelCaseToHumanReadable")
+
+  let result = content
+  const magicString = new MagicString(result)
+
+  // 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)
+    })
+
+  result = magicString.toString()
+
+  // Add import at the beginning if needed
+  if (needsImport) {
+    result =
+      'import { camelCaseToHumanReadable as __camelCaseToHumanReadable } from "@highstate/contract"\n' +
+      result
+  }
+
+  return result
+}
+
+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)
+
+    // Check if we need a comma before adding meta
+    const needsComma = beforeBrace.trim().length > 1 && !beforeBrace.trim().endsWith(",")
+    const comma = needsComma ? "," : ""
+
+    return `${beforeBrace}${comma}
+  meta: {
+    description: \`${description}\`,
+  },
+${afterBrace}`
+  }
+}
+
+function isStructuredValue(value: string, expectedField: string): boolean {
+  const trimmed = value.trim()
+  if (!trimmed.startsWith("{")) {
+    return false
+  }
+
+  // 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)
+}
+
+function getMarkerFunctionName(parentStack: Node[]): string | null {
+  // Look for marker functions like $args, $inputs, $outputs, $secrets
+  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
+      }
+    }
+  }
+  return null
+}
+
+function getParentObjectKey(parentStack: Node[]): string | null {
+  // 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") {
+      return node.key.name
+    }
+  }
+  return null
 }
 
 function isLeadingComment(content: string, node: Node, comment: Comment) {
@@ -63,9 +310,6 @@ function cleanJsdoc(str: string) {
       // remove leading asterisks
       .replace(/^\s*\*/gm, "")
 
-      // remove @schema tag
-      .replace("@schema", "")
-
       // escape backticks and dollar signs
       .replace(/\\/g, "\\\\")
       .replace(/`/g, "\\`")
@@ -73,3 +317,71 @@ function cleanJsdoc(str: string) {
       .trim()
   )
 }
+
+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" &&
+      node.callee.type === "MemberExpression" &&
+      isZodObjectCall(node.callee)
+    ) {
+      return true
+    }
+  }
+  return false
+}
+
+function isZodObjectCall(memberExpression: Node): boolean {
+  if (memberExpression.type !== "MemberExpression") {
+    return false
+  }
+
+  // Handle direct z.object() calls
+  if (
+    memberExpression.object.type === "Identifier" &&
+    memberExpression.object.name === "z" &&
+    memberExpression.property.type === "Identifier" &&
+    memberExpression.property.name === "object"
+  ) {
+    return true
+  }
+
+  // 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"
+  ) {
+    // Recursively check if this is part of a z.* chain
+    return startsWithZodCall(memberExpression.object)
+  }
+
+  return false
+}
+
+function startsWithZodCall(callExpression: Node): boolean {
+  if (!callExpression || callExpression.type !== "CallExpression") {
+    return false
+  }
+
+  if (callExpression.callee.type === "MemberExpression") {
+    // Check if this is a direct z.* call
+    if (
+      callExpression.callee.object.type === "Identifier" &&
+      callExpression.callee.object.name === "z"
+    ) {
+      return true
+    }
+
+    // Recursively check nested calls
+    if (callExpression.callee.object.type === "CallExpression") {
+      return startsWithZodCall(callExpression.callee.object)
+    }
+  }
+
+  return false
+}

package/src/shared/schemas.ts

@@ -0,0 +1,41 @@
+import { z } from "zod"
+
+/**
+ * Schema for the sourceHash configuration in package.json
+ */
+export const sourceHashConfigSchema = z.discriminatedUnion("mode", [
+  z.object({
+    mode: z.literal("manual"),
+    version: z.string(),
+  }),
+  z.object({
+    mode: z.literal("auto"),
+  }),
+  z.object({
+    mode: z.literal("version"),
+  }),
+  z.object({
+    mode: z.literal("none"),
+  }),
+])
+
+/**
+ * Schema for the highstate configuration in package.json
+ */
+export const highstateConfigSchema = z.object({
+  type: z.enum(["source", "library", "worker"]).default("source"),
+  sourceHash: z
+    .union([sourceHashConfigSchema, z.record(z.string(), sourceHashConfigSchema)])
+    .optional(),
+})
+
+/**
+ * Schema for the highstate manifest file
+ */
+export const highstateManifestSchema = z.object({
+  sourceHashes: z.record(z.string(), z.number()).optional(),
+})
+
+export type SourceHashConfig = z.infer<typeof sourceHashConfigSchema>
+export type HighstateConfig = z.infer<typeof highstateConfigSchema>
+export type HighstateManifest = z.infer<typeof highstateManifestSchema>

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

@@ -3,12 +3,18 @@ import { dirname, relative, resolve } from "node:path"
 import { readFile, writeFile } from "node:fs/promises"
 import { fileURLToPath, pathToFileURL } from "node:url"
 import { readPackageJSON, resolvePackageJSON, type PackageJson } from "pkg-types"
-import { sha256 } from "crypto-hash"
+import { crc32 } from "@aws-crypto/crc32"
 import { resolve as importMetaResolve } from "import-meta-resolve"
-
-export type HighstateManifestJson = {
-  sourceHashes?: Record<string, string>
-}
+import { z } from "zod"
+import {
+  type HighstateManifest,
+  type HighstateConfig,
+  type SourceHashConfig,
+  highstateConfigSchema,
+  highstateManifestSchema,
+  sourceHashConfigSchema,
+} from "./schemas"
+import { int32ToBytes } from "./utils"
 
 type FileDependency =
   | {
@@ -23,8 +29,8 @@ type FileDependency =
     }
 
 export class SourceHashCalculator {
-  private readonly dependencyHashes = new Map<string, Promise<string>>()
-  private readonly fileHashes = new Map<string, Promise<string>>()
+  private readonly dependencyHashes = new Map<string, Promise<number>>()
+  private readonly fileHashes = new Map<string, Promise<number>>()
 
   constructor(
     private readonly packageJsonPath: string,
@@ -32,21 +38,117 @@ export class SourceHashCalculator {
     private readonly logger: Logger,
   ) {}
 
-  async writeHighstateManifest(distBasePath: string, distPaths: string[]): Promise<void> {
-    const promises: Promise<{ distPath: string; hash: string }>[] = []
+  /**
+   * Calculates CRC32 hash of a string.
+   */
+  private hashString(input: string): number {
+    return crc32(Buffer.from(input))
+  }
 
-    for (const distPath of distPaths) {
-      const fullPath = resolve(distPath)
+  /**
+   * Gets the highstate configuration from package.json with defaults.
+   */
+  private getHighstateConfig(packageJson: PackageJson): HighstateConfig {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const rawConfig = packageJson.highstate
+    if (!rawConfig) {
+      return { type: "source" }
+    }
 
-      promises.push(
-        this.getFileHash(fullPath).then(hash => ({
-          distPath,
-          hash,
-        })),
+    try {
+      return highstateConfigSchema.parse(rawConfig)
+    } catch (error) {
+      this.logger.warn(
+        { error, packageName: packageJson.name },
+        "invalid highstate configuration, using defaults",
       )
+      return { type: "source" }
+    }
+  }
+
+  /**
+   * Gets the effective source hash configuration with defaults for a specific output.
+   */
+  private getSourceHashConfig(
+    highstateConfig: HighstateConfig,
+    exportKey?: string,
+  ): SourceHashConfig {
+    if (highstateConfig.sourceHash) {
+      // Try to parse as a single config first
+      const singleConfigResult = sourceHashConfigSchema.safeParse(highstateConfig.sourceHash)
+      if (singleConfigResult.success) {
+        return singleConfigResult.data
+      }
+
+      // Try to parse as a record of configs
+      const recordConfigResult = z
+        .record(z.string(), sourceHashConfigSchema)
+        .safeParse(highstateConfig.sourceHash)
+      if (recordConfigResult.success && exportKey) {
+        const perOutputConfig = recordConfigResult.data[exportKey]
+        if (perOutputConfig) {
+          return perOutputConfig
+        }
+      }
+    }
+
+    if (highstateConfig.type === "library") {
+      return { mode: "none" }
+    }
+
+    return { mode: "auto" }
+  }
+
+  async writeHighstateManifest(
+    distBasePath: string,
+    distPathToExportKey: Map<string, string>,
+  ): Promise<void> {
+    const highstateConfig = this.getHighstateConfig(this.packageJson)
+
+    const promises: Promise<{ distPath: string; hash: number }>[] = []
+
+    for (const [distPath, exportKey] of distPathToExportKey) {
+      const fullPath = resolve(distPath)
+      const sourceHashConfig = this.getSourceHashConfig(highstateConfig, exportKey)
+
+      switch (sourceHashConfig.mode) {
+        case "manual":
+          promises.push(
+            Promise.resolve({
+              distPath,
+              hash: this.hashString(sourceHashConfig.version),
+            }),
+          )
+          break
+        case "version":
+          promises.push(
+            Promise.resolve({
+              distPath,
+              hash: this.hashString(this.packageJson.version ?? ""),
+            }),
+          )
+          break
+        case "none":
+          promises.push(
+            Promise.resolve({
+              distPath,
+              hash: 0,
+            }),
+          )
+          break
+        case "auto":
+        default:
+          promises.push(
+            this.getFileHash(fullPath).then(hash => ({
+              distPath,
+              hash,
+            })),
+          )
+          break
+      }
     }
 
-    const manifest: HighstateManifestJson = {
+    const manifest: HighstateManifest = {
       sourceHashes: {},
     }
 
@@ -59,7 +161,7 @@ export class SourceHashCalculator {
     await writeFile(manifestPath, JSON.stringify(manifest, null, 2), "utf8")
   }
 
-  private async getFileHash(fullPath: string): Promise<string> {
+  private async getFileHash(fullPath: string): Promise<number> {
     const existingHash = this.fileHashes.get(fullPath)
     if (existingHash) {
       return existingHash
@@ -71,19 +173,19 @@ export class SourceHashCalculator {
     return hash
   }
 
-  private async calculateFileHash(fullPath: string): Promise<string> {
+  private async calculateFileHash(fullPath: string): Promise<number> {
     const content = await readFile(fullPath, "utf8")
     const fileDeps = this.parseDependencies(fullPath, content)
 
     const hashes = await Promise.all([
-      sha256(content),
+      this.hashString(content),
       ...fileDeps.map(dep => this.getDependencyHash(dep)),
     ])
 
-    return await sha256(hashes.join(""))
+    return crc32(Buffer.concat(hashes.map(int32ToBytes)))
   }
 
-  getDependencyHash(dependency: FileDependency): Promise<string> {
+  getDependencyHash(dependency: FileDependency): Promise<number> {
     const existingHash = this.dependencyHashes.get(dependency.id)
     if (existingHash) {
       return existingHash
@@ -95,7 +197,7 @@ export class SourceHashCalculator {
     return hash
   }
 
-  private async calculateDependencyHash(dependency: FileDependency): Promise<string> {
+  private async calculateDependencyHash(dependency: FileDependency): Promise<number> {
     switch (dependency.type) {
       case "relative": {
         return await this.getFileHash(dependency.fullPath)
@@ -133,6 +235,7 @@ export class SourceHashCalculator {
           this.logger.warn(`package "%s" is not listed in package.json dependencies`, packageName)
         }
 
+        // try to get source hash from manifest first
         let relativePath = relative(dirname(depPackageJsonPath), resolvedPath)
         relativePath = relativePath.startsWith(".") ? relativePath : `./${relativePath}`
 
@@ -142,10 +245,10 @@ export class SourceHashCalculator {
           "highstate.manifest.json",
         )
 
-        let manifest: HighstateManifestJson | undefined
+        let manifest: HighstateManifest | undefined
         try {
           const manifestContent = await readFile(highstateManifestPath, "utf8")
-          manifest = JSON.parse(manifestContent) as HighstateManifestJson
+          manifest = highstateManifestSchema.parse(JSON.parse(manifestContent))
         } catch (error) {
           this.logger.debug(
             { error },
@@ -164,7 +267,7 @@ export class SourceHashCalculator {
         // use the package version as a fallback hash
         // this case will be applied for most npm packages
         this.logger.debug(`using package version as a fallback hash for "%s"`, packageName)
-        return depPackageJson.version ?? "0.0.0"
+        return this.hashString(depPackageJson.version ?? "0.0.0")
       }
     }
   }

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)
+}