@typeonce/effect-machine-devtools 0.23.0

package/src/internal/machineRegistry.ts

@@ -0,0 +1,128 @@
+import * as Effect from "effect/Effect"
+import * as Layer from "effect/Layer"
+import * as SubscriptionRef from "effect/SubscriptionRef"
+import * as DevToolsProtocol from "../DevToolsProtocol.js"
+import type * as MachineRegistry from "../MachineRegistry.js"
+import * as ProjectInspector from "../ProjectInspector.js"
+
+interface PublicApi {
+  readonly MachineRegistry: typeof MachineRegistry.MachineRegistry
+  readonly RegistryError: typeof MachineRegistry.RegistryError
+}
+
+const staleDiagnostic = (failed: DevToolsProtocol.Failed): DevToolsProtocol.Diagnostic => ({
+  severity: "warning",
+  code: "stale-document",
+  message: "Showing the last valid machine document while this module is incomplete.",
+  location: failed.source === null
+    ? null
+    : { file: failed.source.file, line: null, column: null },
+  statePath: null
+})
+
+export const reconcile = (
+  previous: ReadonlyArray<DevToolsProtocol.MachineResult>,
+  next: ReadonlyArray<DevToolsProtocol.MachineResult>
+): ReadonlyArray<DevToolsProtocol.MachineResult> => {
+  const validPrevious = previous.filter((result): result is DevToolsProtocol.Ready | DevToolsProtocol.Partial =>
+    result._tag === "Ready" || result._tag === "Partial"
+  )
+  const previousByKey = new Map(validPrevious.map((result) => [result.key, result]))
+  const previousByFile = new Map<string, Array<DevToolsProtocol.Ready | DevToolsProtocol.Partial>>()
+  for (const result of validPrevious) {
+    const file = result.document.source?.file
+    if (file === undefined) continue
+    const matches = previousByFile.get(file)
+    if (matches === undefined) previousByFile.set(file, [result])
+    else matches.push(result)
+  }
+
+  const emitted = new Set(next.filter((result) => result._tag !== "Failed").map((result) => result.key))
+  return next.flatMap((result): ReadonlyArray<DevToolsProtocol.MachineResult> => {
+    if (result._tag !== "Failed") return [result]
+
+    const moduleFailure = result.diagnostics.some((diagnostic) =>
+      diagnostic.code === "module-load-failed" || diagnostic.code === "machine-export-not-found"
+    )
+    const exact = previousByKey.get(result.key)
+    const candidates = moduleFailure || exact === undefined
+      ? previousByFile.get(result.source.file) ?? []
+      : [exact]
+    const retained = candidates.filter((candidate) => !emitted.has(candidate.key))
+    if (retained.length === 0) return [result]
+
+    for (const candidate of retained) emitted.add(candidate.key)
+    return retained.map((candidate): DevToolsProtocol.Partial => ({
+      _tag: "Partial",
+      protocolVersion: DevToolsProtocol.protocolVersion,
+      key: candidate.key,
+      document: candidate.document,
+      diagnostics: [staleDiagnostic(result), ...result.diagnostics]
+    }))
+  })
+}
+
+const retainedCandidates = (
+  results: ReadonlyArray<DevToolsProtocol.MachineResult>
+): ReadonlyArray<ProjectInspector.Candidate> => {
+  const exportsByFile = new Map<string, Set<string>>()
+  for (const result of results) {
+    if (result._tag !== "Ready" && result._tag !== "Partial") continue
+    const source = result.document.source
+    if (source === null) continue
+    const exportNames = exportsByFile.get(source.file) ?? new Set<string>()
+    if (source.exportName !== null) exportNames.add(source.exportName)
+    exportsByFile.set(source.file, exportNames)
+  }
+  return [...exportsByFile].map(([file, exportNames]) => ({
+    file,
+    exportNames: [...exportNames].sort()
+  }))
+}
+
+const make = (api: PublicApi, options: MachineRegistry.Options) =>
+  Effect.gen(function*() {
+    const inspector = yield* ProjectInspector.ProjectInspector
+    const state = yield* SubscriptionRef.make<MachineRegistry.Snapshot>({
+      protocolVersion: DevToolsProtocol.protocolVersion,
+      revision: 0,
+      results: []
+    })
+
+    const refresh = SubscriptionRef.get(state).pipe(
+      Effect.flatMap((current) =>
+        inspector.inspect({
+          ...options,
+          revision: current.revision + 1,
+          retainedCandidates: retainedCandidates(current.results)
+        }).pipe(
+          Effect.map((results): MachineRegistry.Snapshot => ({
+            protocolVersion: DevToolsProtocol.protocolVersion,
+            revision: current.revision + 1,
+            results: reconcile(current.results, results)
+          }))
+        )
+      ),
+      Effect.tap((next) => SubscriptionRef.set(state, next)),
+      Effect.mapError((cause) =>
+        new api.RegistryError({
+          message: `Could not inspect Effect Machine definitions under ${options.root}`,
+          cause
+        })
+      )
+    )
+
+    yield* refresh
+
+    return api.MachineRegistry.of({
+      get: SubscriptionRef.get(state),
+      changes: SubscriptionRef.changes(state),
+      refresh
+    })
+  })
+
+export const layer = (
+  api: PublicApi,
+  options: MachineRegistry.Options
+): Layer.Layer<MachineRegistry.MachineRegistry, MachineRegistry.RegistryError, ProjectInspector.ProjectInspector> =>
+  Layer.effect(api.MachineRegistry, make(api, options))

package/src/internal/machineSimulator.ts

@@ -0,0 +1,199 @@
+import type * as MachineDocument from "../MachineDocument.js"
+import type * as MachineSimulator from "../MachineSimulator.js"
+
+type State = MachineDocument.State
+type Transition = MachineDocument.Transition
+
+interface Model {
+  readonly states: ReadonlyMap<string, State>
+  readonly order: ReadonlyMap<string, number>
+}
+
+const makeModel = (document: MachineDocument.MachineDocument): Model => ({
+  states: new Map(document.states.map((state) => [state.path, state])),
+  order: new Map(document.states.map((state) => [state.path, state.order]))
+})
+
+const ordered = (model: Model, paths: Iterable<string>): ReadonlyArray<string> =>
+  [...new Set(paths)].sort((left, right) => (model.order.get(left) ?? 0) - (model.order.get(right) ?? 0))
+
+const enter = (model: Model, path: string, active: Set<string>): void => {
+  const state = model.states.get(path)
+  if (state === undefined) return
+  active.add(path)
+  if (state.type === "parallel") {
+    state.children.forEach((child) => enter(model, child, active))
+  } else if (state.type === "compound" && state.initial !== null) {
+    enter(model, state.initial, active)
+  }
+}
+
+const ancestors = (model: Model, path: string): ReadonlyArray<string> => {
+  const result: Array<string> = []
+  let current = model.states.get(path)
+  while (current !== undefined) {
+    result.unshift(current.path)
+    current = current.parent === null ? undefined : model.states.get(current.parent)
+  }
+  return result
+}
+
+const leastCommonAncestor = (model: Model, left: string, right: string): string | null => {
+  const leftAncestors = ancestors(model, left)
+  const rightAncestors = ancestors(model, right)
+  let result: string | null = null
+  const length = Math.min(leftAncestors.length, rightAncestors.length)
+  for (let index = 0; index < length; index++) {
+    if (leftAncestors[index] !== rightAncestors[index]) break
+    result = leftAncestors[index] ?? null
+  }
+  return result
+}
+
+const isDescendant = (model: Model, path: string, ancestor: string): boolean =>
+  path !== ancestor && ancestors(model, path).includes(ancestor)
+
+const candidateEvents = (
+  document: MachineDocument.MachineDocument,
+  activePaths: ReadonlyArray<string>
+): ReadonlyArray<string> => {
+  const active = new Set(activePaths)
+  return [
+    ...new Set(
+      document.transitions.flatMap((transition): ReadonlyArray<string> =>
+        transition.trigger.type === "event" && active.has(transition.source) ? [transition.trigger.event] : []
+      )
+    )
+  ].sort()
+}
+
+const snapshot = (
+  document: MachineDocument.MachineDocument,
+  model: Model,
+  step: number,
+  activePaths: Iterable<string>
+): MachineSimulator.Snapshot => {
+  const active = ordered(model, activePaths)
+  return {
+    step,
+    activePaths: active,
+    candidateEvents: candidateEvents(document, active)
+  }
+}
+
+export const start = (document: MachineDocument.MachineDocument): MachineSimulator.Session => {
+  const model = makeModel(document)
+  const active = new Set<string>()
+  if (document.snapshot === null) {
+    const targetAncestors = ancestors(model, document.initial.target)
+    targetAncestors.forEach((path) => active.add(path))
+    enter(model, document.initial.target, active)
+  } else {
+    document.snapshot.activePaths.forEach((path) => active.add(path))
+  }
+  return { document, snapshot: snapshot(document, model, 0, active) }
+}
+
+const indeterminate = (
+  session: MachineSimulator.Session,
+  event: string,
+  transitions: ReadonlyArray<Transition>,
+  reason: MachineSimulator.Indeterminate["reason"]
+): MachineSimulator.Indeterminate => ({
+  _tag: "Indeterminate",
+  event,
+  transitionIds: transitions.map((transition) => transition.id),
+  session: session.snapshot,
+  reason
+})
+
+const notesFor = (
+  document: MachineDocument.MachineDocument,
+  transition: Transition,
+  nextActive: ReadonlyArray<string>
+): ReadonlyArray<MachineSimulator.Note> => {
+  const notes = new Set<MachineSimulator.Note>(["runtime-effects-skipped"])
+  if (transition.reenter) notes.add("reentry-lifecycles-skipped")
+  if (transition.branches.some((branch) => branch.updates.length > 0)) notes.add("state-updates-skipped")
+  const active = new Set(nextActive)
+  if (
+    document.transitions.some((candidate) =>
+      active.has(candidate.source) &&
+      (candidate.trigger.type === "always" || candidate.trigger.type === "choice" || candidate.trigger.type === "done")
+    )
+  ) {
+    notes.add("automatic-transitions-skipped")
+  }
+  return [...notes]
+}
+
+const nextConfiguration = (
+  session: MachineSimulator.Session,
+  transition: Transition,
+  target: string | null
+): MachineSimulator.Session | undefined => {
+  const document = session.document
+  const model = makeModel(document)
+  if (target === null) {
+    return {
+      document,
+      snapshot: snapshot(document, model, session.snapshot.step + 1, session.snapshot.activePaths)
+    }
+  }
+  if (!model.states.has(target)) return undefined
+
+  const naturalBoundary = leastCommonAncestor(model, transition.source, target)
+  const sourceParent = model.states.get(transition.source)?.parent ?? null
+  const boundary = transition.reenter
+    ? sourceParent === null || naturalBoundary === null
+      ? null
+      : ancestors(model, naturalBoundary).length <= ancestors(model, sourceParent).length
+      ? naturalBoundary
+      : sourceParent
+    : naturalBoundary
+  const active = new Set(session.snapshot.activePaths)
+  for (const path of active) {
+    if (boundary === null || isDescendant(model, path, boundary)) active.delete(path)
+  }
+  ancestors(model, target).forEach((path) => {
+    if (boundary === null || path === boundary || isDescendant(model, path, boundary)) active.add(path)
+  })
+  enter(model, target, active)
+  return { document, snapshot: snapshot(document, model, session.snapshot.step + 1, active) }
+}
+
+export const send = (session: MachineSimulator.Session, event: string): MachineSimulator.StepResult => {
+  const active = new Set(session.snapshot.activePaths)
+  const transitions = session.document.transitions.filter((transition) =>
+    transition.trigger.type === "event" && transition.trigger.event === event && active.has(transition.source)
+  )
+  if (transitions.length === 0) {
+    return {
+      _tag: "Blocked",
+      event,
+      transitionIds: [],
+      session: session.snapshot,
+      reason: "event-not-enabled"
+    }
+  }
+  if (transitions.length > 1) return indeterminate(session, event, transitions, "multiple-transitions")
+  const transition = transitions[0]!
+  if (transition.acceptance === "declinable") {
+    return indeterminate(session, event, transitions, "declinable-transition")
+  }
+  if (transition.branches.length !== 1 || transition.branches[0]?.type === "branch") {
+    return indeterminate(session, event, transitions, "conditional-branches")
+  }
+  const branch = transition.branches[0]!
+  if (branch.selection.kind === "history") return indeterminate(session, event, transitions, "history-target")
+  if (branch.selection.kind === "choice") return indeterminate(session, event, transitions, "choice-target")
+  const next = nextConfiguration(session, transition, branch.target)
+  if (next === undefined) return indeterminate(session, event, transitions, "missing-target")
+  return {
+    _tag: "Applied",
+    event,
+    transitionIds: [transition.id],
+    session: next.snapshot,
+    notes: notesFor(session.document, transition, next.snapshot.activePaths)
+  }
+}

package/src/internal/projectInspector.ts

@@ -0,0 +1,226 @@
+import * as NodeFileSystem from "@effect/platform-node/NodeFileSystem"
+import * as NodePath from "@effect/platform-node/NodePath"
+import * as NodeWorker from "@effect/platform-node/NodeWorker"
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import * as Fiber from "effect/Fiber"
+import * as FileSystem from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import * as Path from "effect/Path"
+import * as Schema from "effect/Schema"
+import * as Worker from "effect/unstable/workers/Worker"
+import { Worker as NodeWorkerThread } from "node:worker_threads"
+import ts from "typescript"
+import * as DevToolsProtocol from "../DevToolsProtocol.js"
+import type * as ProjectInspector from "../ProjectInspector.js"
+
+const defaultInclude = "**/src/**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}"
+
+const defaultExclude = [
+  "**/node_modules/**",
+  "**/.git/**",
+  "**/dist/**",
+  "**/build/**",
+  "**/coverage/**",
+  "**/.data/**",
+  "**/references/**",
+  "**/*.d.ts"
+] as const
+
+interface EvaluationRequest {
+  readonly root: string
+  readonly revision: number
+  readonly candidates: ReadonlyArray<ProjectInspector.Candidate>
+}
+
+interface EvaluationResponse {
+  readonly results: ReadonlyArray<unknown>
+}
+
+const scriptKind = (file: string): ts.ScriptKind => {
+  if (file.endsWith(".tsx")) return ts.ScriptKind.TSX
+  if (file.endsWith(".jsx")) return ts.ScriptKind.JSX
+  if (file.endsWith(".js") || file.endsWith(".mjs") || file.endsWith(".cjs")) return ts.ScriptKind.JS
+  return ts.ScriptKind.TS
+}
+
+const hasExportModifier = (node: ts.Node): boolean =>
+  ts.canHaveModifiers(node) &&
+  ts.getModifiers(node)?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword) === true
+
+const containsHandleCall = (node: ts.Node): boolean => {
+  let found = false
+  const visit = (current: ts.Node): void => {
+    if (found) return
+    if (
+      ts.isCallExpression(current) &&
+      ((ts.isPropertyAccessExpression(current.expression) && current.expression.name.text === "handle") ||
+        (ts.isElementAccessExpression(current.expression) &&
+          ts.isStringLiteral(current.expression.argumentExpression) &&
+          current.expression.argumentExpression.text === "handle"))
+    ) {
+      found = true
+      return
+    }
+    ts.forEachChild(current, visit)
+  }
+  visit(node)
+  return found
+}
+
+export const parseCandidate = (file: string, source: string): ProjectInspector.Candidate | undefined => {
+  const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true, scriptKind(file))
+  if (!containsHandleCall(sourceFile)) return undefined
+
+  const exportNames = new Set<string>()
+  for (const statement of sourceFile.statements) {
+    if (ts.isExportAssignment(statement) && containsHandleCall(statement.expression)) {
+      exportNames.add("default")
+      continue
+    }
+    if (ts.isVariableStatement(statement) && hasExportModifier(statement)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (
+          ts.isIdentifier(declaration.name) && declaration.initializer && containsHandleCall(declaration.initializer)
+        ) {
+          exportNames.add(declaration.name.text)
+        }
+      }
+    }
+  }
+
+  return {
+    file,
+    exportNames: [...exportNames].sort()
+  }
+}
+
+const hasSyntacticErrors = (file: string, source: string): boolean =>
+  ts.transpileModule(source, {
+    fileName: file,
+    reportDiagnostics: true,
+    compilerOptions: {
+      allowJs: true,
+      jsx: ts.JsxEmit.Preserve,
+      target: ts.ScriptTarget.Latest
+    }
+  }).diagnostics?.some((diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error) === true
+
+interface PublicApi {
+  readonly ProjectInspector: typeof ProjectInspector.ProjectInspector
+  readonly DiscoveryError: typeof ProjectInspector.DiscoveryError
+  readonly EvaluationError: typeof ProjectInspector.EvaluationError
+}
+
+const makeDiscovery = (api: PublicApi) =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+    const path = yield* Path.Path
+
+    return (options: ProjectInspector.InspectOptions): Effect.Effect<
+      ReadonlyArray<ProjectInspector.Candidate>,
+      ProjectInspector.DiscoveryError
+    > =>
+      Effect.gen(function*() {
+        const root = path.resolve(options.root)
+        const retainedByFile = new Map(
+          (options.retainedCandidates ?? []).map((candidate) => [candidate.file, candidate])
+        )
+        const files = yield* fs.glob(options.include ?? defaultInclude, {
+          root,
+          exclude: [...defaultExclude, ...(options.exclude ?? [])]
+        })
+        const candidates = yield* Effect.forEach(
+          files.sort(),
+          (file) =>
+            fs.readFileString(path.join(root, file)).pipe(
+              Effect.map((source) => {
+                const candidate = parseCandidate(file, source)
+                if (candidate !== undefined) return candidate
+                const retained = retainedByFile.get(file)
+                return retained !== undefined && hasSyntacticErrors(file, source) ? retained : undefined
+              })
+            ),
+          { concurrency: "unbounded" }
+        )
+        return candidates.filter((candidate): candidate is ProjectInspector.Candidate => candidate !== undefined)
+      }).pipe(
+        Effect.mapError((cause) =>
+          new api.DiscoveryError({
+            message: `Could not discover Effect Machine definitions under ${options.root}`,
+            cause
+          })
+        )
+      )
+  })
+
+const workerBootstrap = new URL("./evaluationWorkerBootstrap.js", import.meta.url)
+const workerRuntime = new URL(
+  import.meta.url.endsWith(".ts") ? "./evaluationWorker.ts" : "./evaluationWorker.js",
+  import.meta.url
+)
+
+const WorkerLayer = NodeWorker.layer(() =>
+  new NodeWorkerThread(workerBootstrap, {
+    execArgv: [],
+    workerData: {
+      runtimeModuleUrl: workerRuntime.href
+    }
+  })
+)
+
+const evaluate = (
+  api: PublicApi,
+  candidates: ReadonlyArray<ProjectInspector.Candidate>,
+  options: ProjectInspector.InspectOptions
+): Effect.Effect<ReadonlyArray<DevToolsProtocol.MachineResult>, ProjectInspector.EvaluationError> => {
+  if (candidates.length === 0) return Effect.succeed([])
+
+  const request: EvaluationRequest = {
+    root: options.root,
+    revision: options.revision ?? 0,
+    candidates
+  }
+
+  return Effect.scoped(
+    Effect.gen(function*() {
+      const platform = yield* Worker.WorkerPlatform
+      const worker = yield* platform.spawn<EvaluationResponse, EvaluationRequest>(0)
+      const response = yield* Deferred.make<EvaluationResponse>()
+      const runner = yield* Effect.forkScoped(
+        worker.run((message) => Deferred.succeed(response, message))
+      )
+      yield* worker.send(request)
+      const message = yield* Effect.raceFirst(Deferred.await(response), Fiber.join(runner))
+      return yield* Effect.forEach(
+        message.results,
+        (result) => Schema.decodeUnknownEffect(DevToolsProtocol.MachineResult)(result)
+      )
+    })
+  ).pipe(
+    Effect.provide(WorkerLayer),
+    Effect.mapError((cause) =>
+      new api.EvaluationError({
+        message: "The isolated machine evaluator failed",
+        cause
+      })
+    )
+  )
+}
+
+const make = (api: PublicApi) =>
+  Effect.gen(function*() {
+    const discover = yield* makeDiscovery(api)
+    const inspect = (options: ProjectInspector.InspectOptions) =>
+      Effect.flatMap(discover(options), (candidates) => evaluate(api, candidates, options))
+    return api.ProjectInspector.of({
+      discover,
+      evaluate: (candidates, options) => evaluate(api, candidates, options),
+      inspect
+    })
+  })
+
+const PlatformLayer = Layer.merge(NodeFileSystem.layer, NodePath.layer)
+
+export const layer = (api: PublicApi): Layer.Layer<ProjectInspector.ProjectInspector> =>
+  Layer.effect(api.ProjectInspector, make(api)).pipe(Layer.provide(PlatformLayer))