@highstate/backend 0.9.16 → 0.9.18

package/src/common/test/tracer.ts

@@ -0,0 +1,359 @@
+import { PassThrough } from "stream"
+import { basename } from "node:path"
+import pino, { levels } from "pino"
+import { test as baseTest, type RunnerTask } from "vitest"
+import { isPromise, omit } from "remeda"
+import * as md from "ts-markdown-builder"
+import { ReproducibleClockProvider, type ClockProvider } from "../clock"
+import { ReproducibleRandomProvider, type RandomProvider } from "../random"
+import { renderTraceEntry } from "./render"
+
+export interface TraceEntry {
+  readonly id: number
+  title?: string
+  render(): string
+}
+
+export function linkTraceEntry(entry: TraceEntry): string {
+  const anchorId = `#trace-${entry.id}`
+
+  if (entry.title) {
+    return md.link(anchorId, `${entry.id}. ${entry.title}`)
+  }
+
+  return md.link(anchorId, entry.id.toString())
+}
+
+export type TestPhase = "arrange" | "act" | "assert"
+
+class CallTraceEntry implements TraceEntry {
+  resolvedEntry?: TraceEntry
+  result?: unknown
+  error?: unknown
+
+  constructor(
+    readonly id: number,
+    private readonly serviceName: string,
+    private readonly methodName: string,
+    private readonly args: unknown[],
+    result?: unknown,
+    error?: unknown,
+  ) {
+    this.result = result
+    this.error = error
+  }
+
+  get title(): string {
+    return `${this.serviceName}.${this.methodName}`
+  }
+
+  render(): string {
+    if (this.resolvedEntry) {
+      // deferred completion - show promise link with ➡️
+      return renderTraceEntry({
+        icon: "➡️",
+        title: this.title,
+        fields: {
+          args: {
+            value: this.args,
+            alwaysRender: true,
+          },
+          result: {
+            value: `${md.code("Promise")}, resolved at ${linkTraceEntry(this.resolvedEntry)}`,
+            raw: true,
+          },
+        },
+      })
+    }
+
+    return renderTraceEntry({
+      icon: "✅",
+      title: this.title,
+      fields: {
+        args: {
+          value: this.args,
+          alwaysRender: true,
+        },
+        result: {
+          value: this.result,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+class CallResultEntry implements TraceEntry {
+  constructor(
+    readonly id: number,
+    private readonly callEntry: TraceEntry,
+    private readonly result?: unknown,
+    private readonly error?: unknown,
+  ) {}
+
+  render(): string {
+    return renderTraceEntry({
+      icon: "↩️",
+      title: linkTraceEntry(this.callEntry),
+      fields: {
+        result: {
+          value: this.result,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+const logLevelIcons: Record<string, string> = {
+  error: "❌",
+  warn: "⚠️",
+  info: "ℹ️",
+  debug: "🔍",
+  trace: "🔬",
+}
+
+class LogTraceEntry implements TraceEntry {
+  constructor(
+    readonly id: number,
+    private readonly level: string,
+    private readonly message: string,
+    private readonly data?: Record<string, unknown>,
+    private readonly error?: unknown,
+  ) {}
+
+  render(): string {
+    return renderTraceEntry({
+      icon: logLevelIcons[this.level] ?? "ℹ️",
+      title: this.level,
+      code: this.message,
+      fields: {
+        data: {
+          value: this.data,
+        },
+        error: {
+          value: this.error,
+        },
+      },
+    })
+  }
+}
+
+export class TestTracer {
+  private readonly traces: Record<TestPhase, TraceEntry[]> = {
+    arrange: [],
+    act: [],
+    assert: [],
+  }
+
+  private _entryCount = 0
+  private _currentPhase: TestPhase = "arrange"
+
+  setPhase(phase: TestPhase) {
+    this._currentPhase = phase
+  }
+
+  readonly logger = pino({ level: "debug" }, this.createLogStream())
+
+  createServiceMock<TService extends object>(name: string, impl: Partial<TService> = {}): TService {
+    return new Proxy(impl as TService, {
+      get: (target, prop) => {
+        // we assume that all get calls via the proxy are method calls
+
+        return this.createServiceMethodMock(
+          name,
+          prop as string,
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+          target[prop as keyof TService] as Function,
+        )
+      },
+    })
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  private createServiceMethodMock(serviceName: string, name: string, base: Function = () => {}) {
+    return new Proxy(base, {
+      apply: (target, thisArg, args) => {
+        try {
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+          const result = target.apply(thisArg, args)
+
+          if (!isPromise(result)) {
+            // record synchronous call
+            this.addEntry(new CallTraceEntry(this.nextEntryId(), serviceName, name, args, result))
+
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return result
+          }
+
+          // create async call trace entry
+          const callEntry = new CallTraceEntry(this.nextEntryId(), serviceName, name, args)
+          this.addEntry(callEntry)
+
+          // wrap the promise to track resolution
+          const wrappedPromise = (result as Promise<unknown>).then(
+            (resolvedValue: unknown) => {
+              if (this.nextEntryId() === callEntry.id + 1) {
+                // immediate completion (no other traces added in between)
+
+                callEntry.result = resolvedValue
+                return resolvedValue
+              }
+
+              // deferred completion - create a separate result entry
+              const resultEntry = new CallResultEntry(this.nextEntryId(), callEntry, resolvedValue)
+
+              this.addEntry(resultEntry)
+              callEntry.resolvedEntry = resultEntry
+
+              return resolvedValue
+            },
+            (rejectedError: unknown) => {
+              if (this.nextEntryId() === callEntry.id + 1) {
+                // immediate error (no other traces added in between)
+
+                callEntry.error = rejectedError
+                throw rejectedError
+              }
+
+              // deferred error - create a separate result entry
+              const resultEntry = new CallResultEntry(
+                this.nextEntryId(),
+                callEntry,
+                undefined,
+                rejectedError,
+              )
+
+              this.addEntry(resultEntry)
+              callEntry.resolvedEntry = resultEntry
+
+              throw rejectedError
+            },
+          )
+
+          return wrappedPromise
+        } catch (error) {
+          // record synchronous error
+          const callEntry = new CallTraceEntry(
+            this.nextEntryId(),
+            serviceName,
+            name,
+            args,
+            undefined,
+            error,
+          )
+
+          this.addEntry(callEntry)
+        }
+      },
+    })
+  }
+
+  nextEntryId(): number {
+    return this._entryCount + 1
+  }
+
+  addEntry(entry: TraceEntry) {
+    this._entryCount += 1
+    this.traces[this._currentPhase].push(entry)
+  }
+
+  private createLogStream() {
+    const stream = new PassThrough()
+
+    stream.on("data", data => {
+      const { level, msg, error, ...other } = JSON.parse(String(data)) as {
+        msg: string
+        level: number
+        error?: string
+      }
+
+      const levelLabel = levels.labels[level]
+      const logEntry = new LogTraceEntry(
+        this.nextEntryId(),
+        levelLabel,
+        msg,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        omit(other as any, ["time", "pid", "hostname"]),
+        error,
+      )
+
+      this.addEntry(logEntry)
+    })
+
+    return stream
+  }
+
+  render(): string {
+    const blocks = Object.entries(this.traces).flatMap(([phase, traces]) => {
+      if (traces.length === 0) {
+        return []
+      }
+
+      return [
+        `## ${phase}\n`,
+        ...traces.map(trace => {
+          const anchorId = `trace-${trace.id}`
+
+          return `### <a id="${anchorId}"></a> ${trace.id}. ${trace.render()}`
+        }),
+      ]
+    })
+
+    return md.joinBlocks(blocks)
+  }
+}
+
+export type TestBaseFixtures = {
+  tracer: TestTracer
+  clock: ClockProvider
+  random: RandomProvider
+}
+
+function camelCaseToKebabCase(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase()
+}
+
+function getFullName(test: RunnerTask): string {
+  let result = camelCaseToKebabCase(test.name)
+
+  while (test.suite) {
+    test = test.suite
+    result = `${camelCaseToKebabCase(test.name)}/${result}`
+  }
+
+  return result.replaceAll(" ", "-")
+}
+
+export const test = baseTest.extend<TestBaseFixtures>({
+  tracer: async ({ task, expect }, use) => {
+    const tracer = new TestTracer()
+
+    await use(tracer)
+
+    const fileName = basename(task.file.name).replace(/\.test\.ts$/, "")
+    const taskName = getFullName(task)
+    const rendered = tracer.render()
+
+    await expect(rendered).toMatchFileSnapshot(`./__traces__/${fileName}/${taskName}.md`)
+  },
+
+  random: async ({ task }, use) => {
+    const random = new ReproducibleRandomProvider(Buffer.from(task.id))
+
+    await use(random)
+  },
+
+  // eslint-disable-next-line no-empty-pattern
+  clock: async ({}, use) => {
+    const clock = new ReproducibleClockProvider()
+
+    await use(clock)
+  },
+})
+
+export const testBase = test

package/src/config.ts

@@ -40,5 +40,9 @@ export async function loadConfig(
     await import("dotenv/config")
   }
 
-  return configSchema.parse(env)
+  try {
+    return configSchema.parse(env)
+  } catch (error) {
+    throw new Error("Failed to parse backend configuration", { cause: error })
+  }
 }

package/src/hotstate/manager.ts

@@ -1,21 +1,17 @@
 import type { HotStateBackend } from "./abstractions"
 import { z } from "zod"
 import { instanceLockSchema, instanceStateSchema, operationSchema } from "../shared"
+import { MemoryHotStateBackend } from "./memory"
 
 export type DataMap = {
-  /**
-   * Master key for a project used to read and write encrypted data.
-   *
-   * If the key is not set, the project is considered locked.
-   */
-  "project-master-key": {
+  "instance-states-loaded": {
     key: [projectId: string]
-    data: z.ZodType<Uint8Array>
+    data: z.ZodBoolean
   }
 }
 
 const dataSchemas: Record<string, z.ZodType> = {
-  "project-master-key": z.instanceof(Uint8Array),
+  "instance-states-loaded": z.boolean(),
 }
 
 export type DataHashSetMap = {
@@ -190,3 +186,7 @@ export class HotStateManager {
     return await this.hotStateBackend.hdel(key.join(":"), field)
   }
 }
+
+export function createTestHotStateManager(): HotStateManager {
+  return new HotStateManager(new MemoryHotStateBackend())
+}

package/src/hotstate/validation.ts

@@ -47,7 +47,6 @@ export class HotStateValidationDecorator implements HotStateBackend {
 
     for (const [field, value] of entries) {
       try {
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
         const validValue = schema.parse(value)
         validEntries.push([field, validValue])
       } catch (error) {

package/src/library/abstractions.ts

@@ -1,4 +1,4 @@
-import type { InstanceModel, CompositeInstance } from "@highstate/contract"
+import type { InstanceModel } from "@highstate/contract"
 import type { LibraryModel, LibraryUpdate, ResolvedInstanceInput } from "../shared"
 
 export type ResolvedUnitSource = {
@@ -8,15 +8,18 @@ export type ResolvedUnitSource = {
   allowedDependencies: string[]
 }
 
-export type InstanceEvaluationResult =
+export type ProjectEvaluationResult =
   | {
       success: true
-      instanceId: string
-      compositeInstances: CompositeInstance[]
+      virtualInstances: InstanceModel[]
+
+      /**
+       * The mapping of top-level composite instance IDs to error messages if any.
+       */
+      topLevelErrors: Record<string, string>
     }
   | {
       success: false
-      instanceId: string
       error: string
     }
 
@@ -24,27 +27,33 @@ export interface LibraryBackend {
   /**
    * Loads the library.
    */
-  loadLibrary(libraryId: string, signal?: AbortSignal): Promise<LibraryModel>
+  loadLibrary(libraryId: string | undefined, signal?: AbortSignal): Promise<LibraryModel>
 
   /**
    * Watches the library for changes.
    */
-  watchLibrary(libraryId: string, signal?: AbortSignal): AsyncIterable<LibraryUpdate[]>
+  watchLibrary(libraryId: string | undefined, signal?: AbortSignal): AsyncIterable<LibraryUpdate[]>
 
   /**
    * Gets the resolved unit sources for the given unit types.
    *
    * If the packages for these units are not resolved, it will resolve them and include in watch list.
    */
-  getResolvedUnitSources(libraryId: string, unitTypes: string[]): Promise<ResolvedUnitSource[]>
+  getResolvedUnitSources(
+    libraryId: string | undefined,
+    unitTypes: string[],
+  ): Promise<ResolvedUnitSource[]>
 
   /**
    * Watches the resolved unit sources for changes.
    * Returns an async iterable that emits each resolved unit source whenever it changes.
    * Does not emit the resolved unit sources for units that have not changed even if the library was reloaded.
+   *
+   * @param libraryId The library ID to watch for resolved unit sources.
+   * @param signal Optional AbortSignal to cancel the watch.
    */
   watchResolvedUnitSources(
-    libraryId: string,
+    libraryId: string | undefined,
     signal?: AbortSignal,
   ): AsyncIterable<ResolvedUnitSource>
 
@@ -57,9 +66,9 @@ export interface LibraryBackend {
    * @param instanceIds The instance ids to evaluate.
    */
   evaluateCompositeInstances(
-    libraryId: string,
+    libraryId: string | undefined,
     allInstances: InstanceModel[],
     resolvedInputs: Record<string, Record<string, ResolvedInstanceInput[]>>,
     instanceIds: string[],
-  ): Promise<InstanceEvaluationResult[]>
+  ): Promise<ProjectEvaluationResult>
 }

package/src/library/local.ts

@@ -1,10 +1,10 @@
-import type { InstanceEvaluationResult, LibraryBackend, ResolvedUnitSource } from "./abstractions"
+import type { LibraryBackend, ProjectEvaluationResult, ResolvedUnitSource } from "./abstractions"
 import type { Logger } from "pino"
 import type {
   PackageResolutionResponse,
   PackageResolutionWorkerData,
 } from "./package-resolution-worker"
-import type { WorkerData, WorkerResponse } from "./worker/protocol"
+import type { WorkerData } from "./worker/protocol"
 import { fileURLToPath } from "node:url"
 import { EventEmitter, on } from "node:events"
 import { Worker } from "node:worker_threads"
@@ -28,7 +28,7 @@ import {
 } from "../shared"
 
 export const localLibraryBackendConfig = z.object({
-  HIGHSTATE_LIBRARY_BACKEND_LOCAL_PACKAGES: stringArrayType.default("@highstate/library"),
+  HIGHSTATE_LIBRARY_BACKEND_LOCAL_PACKAGES: stringArrayType.default(() => ["@highstate/library"]),
   HIGHSTATE_LIBRARY_BACKEND_LOCAL_WATCH_PATHS: stringArrayType.optional(),
 })
 
@@ -149,7 +149,7 @@ export class LocalLibraryBackend implements LibraryBackend {
     allInstances: InstanceModel[],
     resolvedInputs: Record<string, Record<string, ResolvedInstanceInput[]>>,
     instanceIds: string[],
-  ): Promise<InstanceEvaluationResult[]> {
+  ): Promise<ProjectEvaluationResult> {
     this.logger.info("evaluating %d composite instances", instanceIds.length)
 
     const worker = this.createLibraryWorker({
@@ -159,15 +159,8 @@ export class LocalLibraryBackend implements LibraryBackend {
       instanceIds,
     })
 
-    for await (const [event] of on(worker, "message")) {
-      const eventData = event as WorkerResponse
-
-      if (eventData.type === "error") {
-        throw new Error(`Worker error: ${eventData.error}`)
-      }
-
-      this.logger.info("composite instances evaluated successfully")
-      return eventData.results
+    for await (const [event] of on(worker, "message", { signal: AbortSignal.timeout(10_000) })) {
+      return event as ProjectEvaluationResult
     }
 
     throw new Error("Worker ended without sending any response")

package/src/library/worker/evaluator.ts

@@ -1,72 +1,68 @@
 import type { Logger } from "pino"
-import type { InstanceEvaluationResult } from "../abstractions"
+import type { ProjectEvaluationResult } from "../abstractions"
 import type { ResolvedInstanceInput } from "../../shared"
 import {
-  getCompositeInstances,
-  resetEvaluation,
+  getRuntimeInstances,
+  InstanceNameConflictError,
   type Component,
   type InstanceModel,
 } from "@highstate/contract"
 import { errorToString } from "../../common"
 
-export function evaluateInstances(
+export function evaluateProject(
   logger: Logger,
   components: Readonly<Record<string, Component>>,
   allInstances: InstanceModel[],
   resolvedInputs: Record<string, Record<string, ResolvedInstanceInput[]>>,
   instanceIds: string[],
-): InstanceEvaluationResult[] {
-  const results: InstanceEvaluationResult[] = []
+): ProjectEvaluationResult {
+  const errors: Record<string, string> = {}
   const allInstancesMap = new Map(allInstances.map(instance => [instance.id, instance]))
+  const instanceOutputs = new Map<string, Record<string, unknown>>()
 
   for (const instanceId of instanceIds ?? []) {
     try {
       logger.debug({ instanceId }, "evaluating top-level instance")
-      resetEvaluation()
 
-      evaluateInstance(instanceId)
-
-      results.push({
-        success: true,
-        instanceId,
-        compositeInstances: getCompositeInstances().filter(
-          instance =>
-            instanceId.includes(instance.instance.id) || !allInstancesMap.has(instance.instance.id),
-        ),
-      })
+      evaluateInstance(instanceId as InstanceModel["id"])
     } catch (error) {
-      results.push({
-        success: false,
-        instanceId,
-        error: errorToString(error),
-      })
+      errors[instanceId] = errorToString(error)
+
+      if (error instanceof InstanceNameConflictError) {
+        // fail the whole evaluation if there's a name conflict
+        return {
+          success: false,
+          error: error.message,
+        }
+      }
     }
   }
 
-  return results
+  return {
+    success: true,
+    virtualInstances: getRuntimeInstances()
+      .map(instance => instance.instance)
+      // only include top-level composite instances and their children
+      .filter(instance => instanceIds.includes(instance.id) || !allInstancesMap.has(instance.id)),
+    topLevelErrors: errors,
+  }
 
-  function evaluateInstance(
-    instanceId: string,
-    instanceOutputs: Map<string, Record<string, unknown>> = new Map(),
-  ): Record<string, unknown> {
+  function evaluateInstance(instanceId: InstanceModel["id"]): Record<string, unknown> {
     let outputs = instanceOutputs.get(instanceId)
 
     if (!outputs) {
-      outputs = _evaluateInstance(instanceId, instanceOutputs)
+      outputs = _evaluateInstance(instanceId)
       instanceOutputs.set(instanceId, outputs)
     }
 
     return outputs
   }
 
-  function _evaluateInstance(
-    instanceId: string,
-    instanceOutputs: Map<string, Record<string, unknown>>,
-  ): Record<string, unknown> {
+  function _evaluateInstance(instanceId: InstanceModel["id"]): Record<string, unknown> {
     const inputs: Record<string, unknown> = {}
     const instance = allInstancesMap.get(instanceId)
 
-    logger.info("evaluating instance", { instanceId })
+    logger.debug("evaluating instance", { instanceId })
 
     if (!instance) {
       throw new Error(`Instance not found: ${instanceId}`)
@@ -74,7 +70,7 @@ export function evaluateInstances(
 
     for (const [inputName, input] of Object.entries(resolvedInputs[instanceId] ?? {})) {
       inputs[inputName] = input.map(input => {
-        const evaluated = evaluateInstance(input.input.instanceId, instanceOutputs)
+        const evaluated = evaluateInstance(input.input.instanceId)
 
         return evaluated[input.input.output]
       })

package/src/library/worker/loader.lite.ts

@@ -35,6 +35,19 @@ async function _loadLibrary(value: unknown, components: Record<string, Component
     return
   }
 
+  if ("_zod" in value) {
+    // this is a zod schema, we can skip it
+    return
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      await _loadLibrary(item, components)
+    }
+
+    return
+  }
+
   for (const key in value) {
     await _loadLibrary((value as Record<string, unknown>)[key], components)
   }