yukigo 0.2.2 → 0.3.1

package/src/interpreter/components/kernel/commands.ts

@@ -0,0 +1,255 @@
+import { ASTNode, Pattern } from "yukigo-ast";
+import { YukigoKernel } from "./index.js";
+import { ErrorFrame, InterpreterError } from "../../errors.js";
+import { LogicTranslator } from "../logic/LogicTranslator.js";
+import { Scope } from "../logic/LogicEngine.js";
+import { ListTerm } from "../logic/LogicTerm.js";
+import {
+  YuValue,
+  Substitution,
+  isLogicResult,
+  LogicResult,
+  LogicAnswer,
+  LogicTerm,
+} from "../../primitives/index.js";
+import { InterpreterVisitor } from "../evaluators/index.js";
+
+/**
+ * A Continuation is a function that receives a value and decides what is the next Command to execute
+ */
+export type Continuation = (result: YuValue) => ExecutionCommand;
+
+export type TraceEntry = { frame: ErrorFrame; key: string };
+
+export interface ExecutionCommand {
+  readonly name: string;
+  execute(kernel: YukigoKernel): ExecutionCommand | void;
+  createTraceEntry(): TraceEntry | void;
+}
+
+/**
+ * Commands the Kernel to evaluate an AST node.
+ */
+export class EvalCommand implements ExecutionCommand {
+  readonly name = "EVAL";
+
+  constructor(public readonly node: ASTNode) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand {
+    return kernel.evaluator.evaluate(this.node);
+  }
+  createTraceEntry(): TraceEntry {
+    const { constructor, loc } = this.node;
+    const frame = {
+      nodeType: constructor.name,
+      loc,
+    };
+    const startLoc = loc ? `${loc.line}:${loc.column}:` : "";
+    const key = `${startLoc}${constructor.name}`;
+    return { key, frame };
+  }
+}
+
+/**
+ * Commands the Kernel to move to the next step with a produced value.
+ * It triggers the popping of the continuation stack in the kernel.
+ */
+export class StepCommand implements ExecutionCommand {
+  readonly name = "STEP";
+
+  constructor(public readonly value: YuValue) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand | void {
+    return kernel.popAndExecute(this.value);
+  }
+  createTraceEntry() {}
+}
+
+/**
+ * Commands the Kernel to bind a produced value to a continuation.
+ * It pushes the continuation to the kernel's stack and proceeds with the command.
+ */
+export class BindCommand implements ExecutionCommand {
+  readonly name = "BIND";
+
+  constructor(
+    public readonly command: ExecutionCommand,
+    public readonly next: Continuation,
+  ) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand {
+    kernel.pushContinuation(this.next);
+    return this.command;
+  }
+  createTraceEntry() {}
+}
+
+/**
+ * Commands the Kernel to handle multiple branches of execution (non-determinism).
+ * It will try the first one and save the others as choice points.
+ */
+export class ChoiceCommand implements ExecutionCommand {
+  readonly name = "CHOICE";
+
+  constructor(public readonly alternatives: ExecutionCommand[]) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand | void {
+    return kernel.handleChoice(this.alternatives);
+  }
+  createTraceEntry() {}
+}
+
+/**
+ * Commands the Kernel to halt execution due to an error.
+ */
+export class FailCommand implements ExecutionCommand {
+  readonly name = "FAIL";
+
+  constructor(public readonly error: Error) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand | void {
+    throw kernel.buildSemanticError(this.error);
+  }
+  createTraceEntry() {}
+}
+
+// error handling commands
+
+export class RaiseCommand implements ExecutionCommand {
+  readonly name = "RAISE";
+
+  constructor(public readonly exceptionObj: YuValue | InterpreterError) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand | void {
+    // Le decimos al kernel que inicie el proceso de desapilado para buscar un Catch
+    return kernel.handleRaise(this.exceptionObj);
+  }
+  
+  createTraceEntry() {}
+}
+
+/**
+ * A CatchHandler is a function that receives the raised exception (YuValue) 
+ * and decides what Command to execute next (usually the catch block body).
+ */
+export type CatchHandler = (exception: YuValue | InterpreterError) => ExecutionCommand;
+
+export class CatchCommand implements ExecutionCommand {
+  readonly name = "CATCH";
+
+  constructor(
+    public readonly handler: CatchHandler,
+    public readonly innerCommand: ExecutionCommand // El cuerpo del try
+  ) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand {
+    // 1. Registramos este manejador de errores en el Kernel
+    kernel.pushCatchHandler(this.handler);
+    
+    // 2. Ejecutamos el cuerpo del try envuelto en una limpieza
+    // Si el innerCommand termina con éxito (sin errores), necesitamos sacar el handler de la pila
+    return new BindCommand(this.innerCommand, (result) => {
+      kernel.popCatchHandler(); // Removemos el handler porque no hubo error
+      return new StepCommand(result);
+    });
+  }
+  
+  createTraceEntry() {}
+}
+
+
+// Specific commands for LogicRuntime
+
+/**
+ * Commands the Kernel to stop execution and backtrack due to logical failure.
+ */
+export class BacktrackCommand implements ExecutionCommand {
+  readonly name = "BACKTRACK";
+
+  constructor() {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand | void {
+    // the backtracking is delegated to the kernel because it manipulates the execution stack
+    return kernel.handleBacktrack();
+  }
+  createTraceEntry() {}
+}
+
+export class NotCommand implements ExecutionCommand {
+  readonly name = "NOT";
+
+  constructor(
+    public readonly innerGoalCmd: ExecutionCommand,
+    public readonly currentSubsts: Substitution,
+  ) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand {
+    const isolatedContext = kernel.evaluator.getContext().clone();
+    const isolatedEvaluator = new InterpreterVisitor(isolatedContext);
+    const isolatedKernel = new YukigoKernel(isolatedEvaluator, "first");
+
+    // Clone substs to avoid leaking bindings from the inner search
+    const result = isolatedKernel.run(this.innerGoalCmd);
+    if (isLogicResult(result) && result.allSuccessful())
+      return new BacktrackCommand();
+
+    return new StepCommand(
+      new LogicResult([new LogicAnswer(true, new Map(this.currentSubsts))]),
+    );
+  }
+  createTraceEntry() {}
+}
+
+export class FindallCommand implements ExecutionCommand {
+  readonly name = "FINDALL";
+
+  constructor(
+    public readonly template: Pattern,
+    public readonly bag: Pattern,
+    public readonly innerGoalCmd: ExecutionCommand,
+    public readonly currentSubsts: Substitution,
+    public readonly scope: Scope,
+    public readonly translator: LogicTranslator,
+  ) {}
+
+  execute(kernel: YukigoKernel): ExecutionCommand {
+    // we need to _find all_ (jaja lol) successful branches
+    const isolatedContext = kernel.evaluator.getContext().clone();
+    const isolatedEvaluator = new InterpreterVisitor(isolatedContext);
+    const isolatedKernel = new YukigoKernel(isolatedEvaluator, "all");
+
+    // run inner goal - it will return an array of LogicResult if successful
+    const results = isolatedKernel.run(this.innerGoalCmd);
+    const gathered: LogicTerm[] = [];
+
+    if (Array.isArray(results)) {
+      for (const res of results) {
+        if (isLogicResult(res) && res.allSuccessful()) {
+          // then we extract all solutions and instantiate the template
+          res.getSuccessfulSolutions().forEach((solutionEnv) => {
+            const templateTerm = this.translator.patternToTerm(
+              this.template,
+              this.scope,
+            );
+            gathered.push(templateTerm.instantiate(solutionEnv));
+          });
+        }
+      }
+    }
+
+    // then we build a logic list
+    const resultList = new ListTerm(gathered);
+    const bagTerm = this.translator.patternToTerm(this.bag, this.scope);
+
+    // then we try to unify the list with the bag
+    const finalSubsts = new Map(this.currentSubsts);
+    if (bagTerm.unify(resultList, finalSubsts))
+      return new StepCommand(
+        new LogicResult([new LogicAnswer(true, finalSubsts)]),
+      );
+
+    // finally if unification fails, findall fails
+    return new BacktrackCommand();
+  }
+  createTraceEntry() {}
+}

package/src/interpreter/components/kernel/index.ts

@@ -0,0 +1,222 @@
+import {
+  CatchHandler,
+  Continuation,
+  ExecutionCommand,
+} from "./commands.js";
+import { boolean, EnvStack } from "../../utils.js";
+import { ErrorFrame, InterpreterError } from "../../errors.js";
+import { YuNil, YuValue } from "../../primitives/index.js";
+import { Evaluator } from "../evaluators/BaseEvaluator.js";
+
+export type LogicSearchMode = "first" | "all" | "stream";
+
+export interface ChoicePoint {
+  alternatives: ExecutionCommand[];
+  continuationStack: Continuation[];
+  envSnapshot: EnvStack;
+}
+
+export class YukigoKernel {
+  public readonly kid = Math.floor(Math.random() * 9999);
+  private logicalTrace: ExecutionCommand[] = [];
+  private continuationStack: Continuation[] = [];
+  private choiceStack: ChoicePoint[] = [];
+  private finalResult: YuValue | undefined;
+  private searchExhausted = false;
+
+  private catchHandlerStack: { handler: CatchHandler; continuationDepth: number }[] = [];
+
+  constructor(
+    public readonly evaluator: Evaluator,
+    private readonly mode: LogicSearchMode = "first",
+  ) {}
+
+  /**
+   * Pushes a continuation to the logical stack.
+   */
+  public pushContinuation(cont: Continuation): void {
+    this.continuationStack.push(cont);
+  }
+
+  /**
+   * Pops a continuation from the stack and executes it with the provided value.
+   * If the stack is empty, sets the final result.
+   */
+  public popAndExecute(value: YuValue): ExecutionCommand | void {
+    const next = this.continuationStack.pop();
+    if (!next) {
+      this.finalResult = value;
+      return;
+    }
+    return next(value);
+  }
+
+  public pushCatchHandler(handler: CatchHandler): void {
+    // Save current continuation stack length so we know where to unwind if an error is raised inside the try block
+    this.catchHandlerStack.push({
+      handler,
+      continuationDepth: this.continuationStack.length,
+    });
+  }
+
+  public popCatchHandler(): CatchHandler | undefined {
+    const entry = this.catchHandlerStack.pop();
+    return entry?.handler;
+  }
+
+  /**
+   * Handles RaiseCommand.
+   */
+  public handleRaise(
+    exception: YuValue | InterpreterError,
+  ): ExecutionCommand | void {
+    const entry = this.catchHandlerStack.pop();
+    if (!entry) {
+      // if no catch found, we have no other option than to throw the error and break the flow.
+      if (exception instanceof InterpreterError) {
+        throw this.buildSemanticError(exception);
+      } else {
+        // TODO: I think this if-else is unnecessary
+        throw this.buildSemanticError(
+          new InterpreterError("UncaughtException", String(exception)),
+        );
+      }
+    }
+
+    // Unwind continuation stack to the point where the try block was entered
+    this.continuationStack.length = entry.continuationDepth;
+
+    return entry.handler(exception);
+  }
+
+  /**
+   * Handles a choice point by trying the first alternative and saving the others.
+   */
+  public handleChoice(
+    alternatives: ExecutionCommand[],
+  ): ExecutionCommand | void {
+    if (alternatives.length === 0) return this.handleBacktrack();
+
+    const [first, ...rest] = alternatives;
+
+    if (rest.length > 0) {
+      this.choiceStack.push({
+        alternatives: rest,
+        continuationStack: [...this.continuationStack],
+        envSnapshot: this.evaluator.getContext().cloneEnv(),
+      });
+    }
+
+    return first;
+  }
+
+  /**
+   * Attempts to backtrack to the last saved choice point.
+   */
+  public handleBacktrack(): ExecutionCommand {
+    const lastChoice = this.choiceStack.pop();
+
+    if (!lastChoice) {
+      // logic tree is empty sooo
+      this.searchExhausted = true;
+      this.continuationStack = [];
+      return boolean(false);
+    }
+
+    this.searchExhausted = false;
+
+    // clones the stack and environment
+    this.continuationStack = [...lastChoice.continuationStack];
+    const clonedEnv = this.evaluator
+      .getContext()
+      .cloneEnv(lastChoice.envSnapshot);
+    this.evaluator.getContext().setEnv(clonedEnv);
+
+    const [next, ...remaining] = lastChoice.alternatives;
+
+    if (remaining.length > 0) {
+      this.choiceStack.push({
+        ...lastChoice,
+        alternatives: remaining,
+      });
+    }
+
+    return next;
+  }
+  // TODO: remove this f- any
+  public run(initialCommand: ExecutionCommand): any {
+    const stream = this.executionStream(initialCommand);
+
+    switch (this.mode) {
+      case "stream":
+        return stream;
+      case "first":
+        const result = stream.next();
+        return result.done ? undefined : result.value;
+      case "all":
+        return Array.from(stream);
+
+      default:
+        throw new Error(`Output mode "${this.mode}" not supported.`);
+    }
+  }
+
+  private *executionStream(
+    initialCommand: ExecutionCommand,
+  ): Generator<YuValue, void, unknown> {
+    let current: ExecutionCommand | void = initialCommand;
+    this.searchExhausted = false;
+    let steps = 0;
+
+    while (current) {
+      steps++;
+      this.logicalTrace.push(current);
+      // cleans the older traces to avoid consuming memory
+      if (this.logicalTrace.length > 50) this.logicalTrace.shift();
+
+      current = current.execute(this);
+
+      if (!current) {
+        if (this.searchExhausted) break;
+        yield this.finalResult || YuNil.getInstance();
+        current = this.handleBacktrack();
+      }
+    }
+  }
+
+  public getLogicalTrace() {
+    return this.logicalTrace;
+  }
+
+  public buildSemanticError(baseError: Error): Error {
+    if (baseError.constructor.name === "FailedAssert") return baseError;
+
+    const frames = this.getStackFromTrace();
+
+    if (baseError instanceof InterpreterError) {
+      if (baseError.frames.length === 0) {
+        frames.forEach((f) => baseError.pushFrame(f));
+      }
+      return baseError;
+    }
+
+    const newErr = new InterpreterError("Yukigo VM Error", baseError.message);
+    frames.forEach((f) => newErr.pushFrame(f));
+    return newErr;
+  }
+
+  private getStackFromTrace(): ErrorFrame[] {
+    const frames: ErrorFrame[] = [];
+    let index = this.logicalTrace.length - 1;
+    // loops through logicalTrace and collects traces
+    for (index; index >= 0; index--) {
+      const cmd = this.logicalTrace[index];
+      const trace = cmd.createTraceEntry();
+      // not all commands leave traces
+      if (!trace) continue;
+      frames.push(trace.frame);
+      if (frames.length >= 10) break;
+    }
+    return frames;
+  }
+}