@highstate/cli 0.9.14 → 0.9.16

package/src/shared/library-loader.ts

@@ -0,0 +1,113 @@
+import type { Logger } from "pino"
+import {
+  type Component,
+  type ComponentModel,
+  type Entity,
+  isComponent,
+  isEntity,
+  isUnitModel,
+  originalCreate,
+} from "@highstate/contract"
+import { serializeFunction } from "@pulumi/pulumi/runtime/index.js"
+import { Crc32, crc32 } from "@aws-crypto/crc32"
+import { encode } from "@msgpack/msgpack"
+import { int32ToBytes } from "@highstate/backend/shared"
+
+export type Library = Readonly<{
+  components: Readonly<Record<string, ComponentModel>>
+  entities: Readonly<Record<string, Entity>>
+}>
+
+export async function loadLibrary(logger: Logger, modulePaths: string[]): Promise<Library> {
+  const modules: Record<string, unknown> = {}
+  for (const modulePath of modulePaths) {
+    try {
+      logger.debug({ modulePath }, "loading module")
+      modules[modulePath] = await import(modulePath)
+
+      logger.debug({ modulePath }, "module loaded")
+    } catch (err) {
+      logger.error({ modulePath, err }, "module load failed")
+    }
+  }
+
+  const components: Record<string, ComponentModel> = {}
+  const entities: Record<string, Entity> = {}
+
+  await _loadLibrary(modules, components, entities)
+
+  logger.info(
+    {
+      componentCount: Object.keys(components).length,
+      entityCount: Object.keys(entities).length,
+    },
+    "library loaded",
+  )
+
+  logger.trace({ components, entities }, "library content")
+
+  return { components, entities }
+}
+
+async function _loadLibrary(
+  value: unknown,
+  components: Record<string, ComponentModel>,
+  entities: Record<string, Entity>,
+): Promise<void> {
+  if (isComponent(value)) {
+    const entityHashes: number[] = []
+    for (const entity of value.entities.values()) {
+      entity.definitionHash ??= calculateEntityDefinitionHash(entity)
+      entityHashes.push(entity.definitionHash)
+    }
+
+    components[value.model.type] = value.model
+    value.model.definitionHash = await calculateComponentDefinitionHash(value, entityHashes)
+
+    return
+  }
+
+  if (isEntity(value)) {
+    entities[value.type] = value
+    entities[value.type].definitionHash ??= calculateEntityDefinitionHash(value)
+
+    // @ts-expect-error remove the schema since it's not needed in the designer
+    delete value.schema
+    return
+  }
+
+  if (typeof value !== "object" || value === null) {
+    return
+  }
+
+  for (const key in value) {
+    await _loadLibrary((value as Record<string, unknown>)[key], components, entities)
+  }
+}
+
+async function calculateComponentDefinitionHash(
+  component: Component,
+  entityHashes: number[],
+): Promise<number> {
+  const result = new Crc32()
+
+  // 1. include the full component model
+  result.update(encode(component.model))
+
+  if (!isUnitModel(component.model)) {
+    // 2. for composite components, include the content of the serialized create function
+    const serializedCreate = await serializeFunction(component[originalCreate])
+    result.update(Buffer.from(serializedCreate.text))
+  }
+
+  // 3. include the hashes of all entities
+  for (const entityHash of entityHashes) {
+    result.update(int32ToBytes(entityHash))
+  }
+
+  return result.digest()
+}
+
+function calculateEntityDefinitionHash(entity: Entity): number {
+  return crc32(encode(entity))
+}

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

@@ -0,0 +1,209 @@
+import { describe, it, expect } from "vitest"
+import { applySchemaTransformations } from "./schema-transformer"
+
+describe("applySchemaTransformations", () => {
+  it("should transform simple values to entity/schema structure", async () => {
+    const input = `
+const spec = {
+  inputs: {
+    /**
+     * The Kubernetes cluster to deploy on.
+     */
+    cluster: clusterEntity,
+  },
+  args: {
+    /**
+     * The port number to use.
+     */
+    port: Type.Number(),
+  },
+}`
+
+    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.`")
+  })
+
+  it("should inject description into existing meta field", async () => {
+    const input = `
+const spec = {
+  args: {
+    /**
+     * The API token for authentication.
+     */
+    token: {
+      schema: Type.String(),
+      meta: {
+        displayName: "API Token",
+        sensitive: true,
+      },
+    },
+  },
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    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) =>")
+  })
+
+  it("should add meta field if it doesn't exist in structured object", async () => {
+    const input = `
+const spec = {
+  inputs: {
+    /**
+     * The target endpoint.
+     */
+    endpoint: {
+      entity: endpointEntity,
+      required: false,
+    },
+  },
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("entity: endpointEntity")
+    expect(result).toContain("required: false")
+    expect(result).toContain("meta: {")
+    expect(result).toContain("description: `The target endpoint.`")
+  })
+
+  it("should handle $args marker function", async () => {
+    const input = `
+const spec = {
+  args: $args({
+    /**
+     * The configuration file path.
+     */
+    configPath: Type.String(),
+  }),
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("schema: Type.String()")
+    expect(result).toContain("description: `The configuration file path.`")
+  })
+
+  it("should handle $inputs marker function", async () => {
+    const input = `
+const spec = {
+  inputs: $inputs({
+    /**
+     * The source data.
+     */
+    source: dataEntity,
+  }),
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("entity: dataEntity")
+    expect(result).toContain("description: `The source data.`")
+  })
+
+  it("should handle $outputs marker function", async () => {
+    const input = `
+const spec = {
+  outputs: $outputs({
+    /**
+     * The processed result.
+     */
+    result: resultEntity,
+  }),
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("entity: resultEntity")
+    expect(result).toContain("description: `The processed result.`")
+  })
+
+  it("should handle $secrets marker function", async () => {
+    const input = `
+const spec = {
+  secrets: $secrets({
+    /**
+     * The database password.
+     */
+    dbPassword: Type.String(),
+  }),
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("schema: Type.String()")
+    expect(result).toContain("description: `The database password.`")
+  })
+
+  it("should ignore properties without JSDoc comments", async () => {
+    const input = `
+const spec = {
+  inputs: {
+    cluster: clusterEntity,
+    /**
+     * Only this one has a comment.
+     */
+    endpoint: endpointEntity,
+  },
+}`
+
+    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.`")
+  })
+
+  it("should ignore properties not in target objects", async () => {
+    const input = `
+const config = {
+  /**
+   * This should not be transformed.
+   */
+  someProperty: "value",
+}
+
+const spec = {
+  inputs: {
+    /**
+     * This should be transformed.
+     */
+    cluster: clusterEntity,
+  },
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain('someProperty: "value"') // unchanged
+    expect(result).toContain("entity: clusterEntity") // transformed
+  })
+
+  it("should clean JSDoc comments properly", async () => {
+    const input = `
+const spec = {
+  args: {
+    /**
+     * This is a description with \`backticks\` and \${template} literals.
+     * It also has multiple lines.
+     */
+    value: Type.String(),
+  },
+}`
+
+    const result = await applySchemaTransformations(input)
+
+    expect(result).toContain("schema: Type.String()")
+    expect(result).toContain(
+      "description: `This is a description with \\`backticks\\` and \\${template} literals.",
+    )
+    expect(result).toContain("It also has multiple lines.`")
+  })
+})

package/src/shared/schema-transformer.ts

@@ -22,31 +22,135 @@ export async function applySchemaTransformations(content: string): Promise<strin
   const magicString = new MagicString(content)
   const { program, comments } = await parseAsync("file.ts", content)
 
+  const parentStack: Node[] = []
+
   walk(program, {
     enter(node) {
+      parentStack.push(node)
+
       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)
+        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}\`,
+  },
 }`,
-      )
+        )
+      }
+    },
+    leave() {
+      parentStack.pop()
     },
   })
 
   return magicString.toString()
 }
 
+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)) {
+    // 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
+    }
+
+    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) {
   if (comment.end > node.start) {
     return false
@@ -63,9 +167,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, "\\`")

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>