yukigo 0.2.0 → 0.2.2

package/dist/src/interpreter/components/runtimes/FunctionRuntime.js

@@ -0,0 +1,149 @@
+import { UnguardedBody, Sequence, Return, Function, isRuntimeFunction, } from "yukigo-ast";
+import { PatternMatcher } from "../PatternMatcher.js";
+import { InterpreterError } from "../../errors.js";
+import { EnvBuilderVisitor } from "../EnvBuilder.js";
+import { valueToCPS } from "../../trampoline.js";
+import { RuntimeContext } from "../RuntimeContext.js";
+import { InterpreterVisitor } from "../Visitor.js";
+class NonExhaustivePatterns extends InterpreterError {
+    constructor(funcName) {
+        super("PatternMatch", `Non-exhaustive patterns in '${funcName}'`);
+    }
+}
+export class FunctionRuntime {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    apply(func, args, k) {
+        const funcName = func.identifier;
+        const equations = func.equations;
+        const oldEnv = this.context.env;
+        if (this.context.config.debug)
+            console.log(`[FunctionRuntime] Applying function: ${funcName} with args:`, args);
+        const tryNextEquation = (eqIndex) => {
+            if (eqIndex >= equations.length) {
+                this.context.setEnv(oldEnv);
+                throw new NonExhaustivePatterns(funcName ?? "<anonymous>");
+            }
+            const eq = equations[eqIndex];
+            if (eq.patterns.length !== args.length)
+                return () => tryNextEquation(eqIndex + 1);
+            const bindings = [];
+            return this.patternsMatch(eq, args, bindings, (isMatch) => {
+                if (!isMatch)
+                    return () => tryNextEquation(eqIndex + 1);
+                if (this.context.config.debug)
+                    console.log(`[FunctionRuntime] Match successful for ${funcName} equation ${eqIndex}`);
+                const localEnv = new Map(bindings);
+                if (func.closure)
+                    this.context.setEnv(func.closure);
+                this.context.pushEnv(localEnv);
+                const wrappedK = (res) => {
+                    this.context.setEnv(oldEnv);
+                    return k(res);
+                };
+                const evaluatorFactory = (ctx) => new InterpreterVisitor(ctx);
+                const body = eq.body;
+                // UnguardedBody
+                if (body instanceof UnguardedBody)
+                    return this.evaluateSequence(body.sequence, this.context, evaluatorFactory, wrappedK);
+                // GuardedBody
+                return () => {
+                    if (Array.isArray(body) && body.length > 0) {
+                        const prototypeBody = body[0].body;
+                        if (prototypeBody instanceof Sequence)
+                            this.preloadDefinitions(prototypeBody, evaluatorFactory);
+                    }
+                    const tryNextGuard = (guardIndex) => {
+                        if (guardIndex >= body.length) {
+                            this.context.setEnv(oldEnv);
+                            return () => tryNextEquation(eqIndex + 1);
+                        }
+                        const evaluator = evaluatorFactory(this.context);
+                        const guard = body[guardIndex];
+                        return evaluator.evaluate(guard.condition, (cond) => {
+                            if (cond !== true)
+                                return () => tryNextGuard(guardIndex + 1);
+                            if (!(guard.body instanceof Sequence))
+                                return evaluator.evaluate(guard.body, wrappedK);
+                            return this.evaluateSequence(guard.body, this.context, evaluatorFactory, wrappedK);
+                        });
+                    };
+                    return tryNextGuard(0);
+                };
+            });
+        };
+        return tryNextEquation(0);
+    }
+    applyArguments(func, args) {
+        if (args.length < func.arity) {
+            return valueToCPS({
+                ...func,
+                pendingArgs: args,
+            });
+        }
+        const argsToConsume = args.slice(0, func.arity);
+        const remainingArgs = args.slice(func.arity);
+        const evaluatedArgs = argsToConsume.map((arg) => typeof arg === "function" ? arg() : arg);
+        return (cont) => () => this.apply(func, evaluatedArgs, (result) => {
+            if (remainingArgs.length > 0) {
+                if (isRuntimeFunction(result)) {
+                    const nextArgs = result.pendingArgs
+                        ? [...result.pendingArgs, ...remainingArgs]
+                        : remainingArgs;
+                    return this.applyArguments(result, nextArgs)(cont);
+                }
+                else {
+                    throw new InterpreterError("Application", `Too many arguments provided. Result was '${result}' (not a function), but had ${remainingArgs.length} args left.`);
+                }
+            }
+            return cont(result);
+        });
+    }
+    preloadDefinitions(seq, evaluatorFactory) {
+        const ctx = new RuntimeContext();
+        new EnvBuilderVisitor(ctx).build(seq.statements);
+        const evaluator = evaluatorFactory(ctx);
+        for (const stmt of seq.statements) {
+            if (stmt instanceof Function || stmt instanceof Return)
+                continue;
+            evaluator.evaluate(stmt, (val) => val);
+        }
+    }
+    patternsMatch(eq, args, bindings, k) {
+        const matchNext = (index) => {
+            if (index >= args.length)
+                return k(true);
+            const matcher = new PatternMatcher(args[index], bindings, this.context);
+            return eq.patterns[index].accept(matcher)((isMatch) => {
+                if (!isMatch)
+                    return k(false);
+                return () => matchNext(index + 1);
+            });
+        };
+        return matchNext(0);
+    }
+    evaluateSequence(seq, ctx, evaluatorFactory, k) {
+        new EnvBuilderVisitor(ctx).build(seq.statements);
+        const evaluator = evaluatorFactory(ctx);
+        const evaluateNext = (index, lastResult) => {
+            if (index >= seq.statements.length)
+                return k(lastResult);
+            const stmt = seq.statements[index];
+            if (stmt instanceof Function)
+                return () => evaluateNext(index + 1, lastResult);
+            if (stmt instanceof Return) {
+                if (!stmt.body)
+                    throw new Error("[FunctionRuntime]: Return \`body\` was undefined");
+                return evaluator.evaluate(stmt.body, k);
+            }
+            else {
+                return evaluator.evaluate(stmt, (result) => {
+                    return () => evaluateNext(index + 1, result);
+                });
+            }
+        };
+        return evaluateNext(0, undefined);
+    }
+}

package/dist/src/interpreter/components/runtimes/LazyRuntime.d.ts

@@ -0,0 +1,19 @@
+import { PrimitiveValue, RangeExpression, ConsExpression, ListBinaryOperation } from "yukigo-ast";
+import { ExpressionEvaluator } from "../../utils.js";
+import { Continuation, Thunk } from "../../trampoline.js";
+import { RuntimeContext } from "../RuntimeContext.js";
+export declare class LazyRuntime {
+    private context;
+    constructor(context: RuntimeContext);
+    realizeList<R = PrimitiveValue[]>(val: PrimitiveValue, k: Continuation<PrimitiveValue[], R>): Thunk<R>;
+    evaluateRange(node: RangeExpression, evaluator: ExpressionEvaluator, k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    evaluateCons(node: ConsExpression, evaluator: ExpressionEvaluator, k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    evaluateConcat(left: PrimitiveValue, right: PrimitiveValue, k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    evaluateConcatLazy(node: ListBinaryOperation, evaluator: ExpressionEvaluator, k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    deepEqual<R = boolean>(a: PrimitiveValue, b: PrimitiveValue, k: Continuation<boolean, R>): Thunk<R>;
+    private isPlainObject;
+    private isCollection;
+    private isListLike;
+    private deepEqualCollection;
+    private deepEqualObject;
+}

package/dist/src/interpreter/components/runtimes/LazyRuntime.js

@@ -0,0 +1,269 @@
+import { isLazyList, } from "yukigo-ast";
+import { createMemoizedStream, isMemoizedList, } from "../PatternMatcher.js";
+import { idContinuation, trampoline, } from "../../trampoline.js";
+export class LazyRuntime {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    realizeList(val, k) {
+        if (Array.isArray(val))
+            return k(val);
+        if (typeof val === "string")
+            return k(val.split(""));
+        if (isLazyList(val)) {
+            const result = [];
+            const iter = val.generator();
+            const next = () => {
+                const step = iter.next();
+                if (step.done)
+                    return k(result);
+                if (step.value === undefined)
+                    throw new Error("LazyList yielded undefined");
+                result.push(step.value);
+                return () => next();
+            };
+            return next();
+        }
+        throw new Error(`Expected List or LazyList, got ${typeof val}`);
+    }
+    evaluateRange(node, evaluator, k) {
+        return evaluator.evaluate(node.start, (startVal) => {
+            if (typeof startVal !== "number")
+                throw new Error("Range start must be a number");
+            const hasEnd = node.end != null;
+            const finishWithStep = (step) => {
+                if (!hasEnd) {
+                    return k(createMemoizedStream(function* () {
+                        let current = startVal;
+                        while (true) {
+                            yield current;
+                            current += step;
+                        }
+                    }));
+                }
+                return evaluator.evaluate(node.end, (endVal) => {
+                    if (typeof endVal !== "number")
+                        throw new Error("Range end must be a number");
+                    const cond = step > 0 ? (c) => c <= endVal : (c) => c >= endVal;
+                    if (this.context.config.lazyLoading) {
+                        return k(createMemoizedStream(function* () {
+                            let current = startVal;
+                            while (cond(current)) {
+                                yield current;
+                                current += step;
+                            }
+                        }));
+                    }
+                    const result = [];
+                    let current = startVal;
+                    while (cond(current)) {
+                        result.push(current);
+                        current += step;
+                    }
+                    return k(result);
+                });
+            };
+            if (node.step) {
+                return evaluator.evaluate(node.step, (secondVal) => {
+                    if (typeof secondVal !== "number")
+                        throw new Error("Range step must be a number");
+                    const step = secondVal - startVal;
+                    if (step === 0)
+                        throw new Error("Range step cannot be zero");
+                    return finishWithStep(step);
+                });
+            }
+            return finishWithStep(1);
+        });
+    }
+    evaluateCons(node, evaluator, k) {
+        const ctx = this.context;
+        const capturedEnv = ctx.clone();
+        return evaluator.evaluate(node.head, (head) => {
+            if (ctx.config.lazyLoading) {
+                const consState = {
+                    head,
+                    tailExpr: node.tail,
+                    evaluator,
+                    capturedEnv,
+                    realizedTail: undefined,
+                };
+                const consList = {
+                    type: "LazyList",
+                    generator: function* () {
+                        let current = consState;
+                        while (current !== undefined && current !== null) {
+                            if (current.tailExpr !== undefined) {
+                                yield current.head;
+                                if (current.realizedTail === undefined) {
+                                    const prevEnv = ctx.env;
+                                    ctx.setEnv(current.capturedEnv);
+                                    try {
+                                        current.realizedTail = trampoline(current.evaluator.evaluate(current.tailExpr, idContinuation));
+                                    }
+                                    finally {
+                                        ctx.setEnv(prevEnv);
+                                    }
+                                }
+                                current = current.realizedTail;
+                            }
+                            else if (isLazyList(current)) {
+                                const memoized = current;
+                                if (isMemoizedList(memoized) && memoized._consState) {
+                                    current = memoized._consState;
+                                }
+                                else {
+                                    const iter = current.generator();
+                                    let step = iter.next();
+                                    while (!step.done) {
+                                        yield step.value;
+                                        step = iter.next();
+                                    }
+                                    break;
+                                }
+                            }
+                            else if (Array.isArray(current) ||
+                                typeof current === "string") {
+                                for (const x of current)
+                                    yield x;
+                                break;
+                            }
+                            else {
+                                throw new Error(`Invalid tail type for Cons: ${typeof current}`);
+                            }
+                        }
+                    },
+                };
+                const memoized = createMemoizedStream(() => consList.generator());
+                memoized._consState = consState;
+                return k(memoized);
+            }
+            // Eager behavior
+            return evaluator.evaluate(node.tail, (tail) => {
+                if (typeof tail === "string")
+                    return k(head + tail);
+                if (isLazyList(tail) || !Array.isArray(tail))
+                    throw new Error("Expected Array in eager Cons");
+                return k([head, ...tail]);
+            });
+        });
+    }
+    evaluateConcat(left, right, k) {
+        if (this.context.config.lazyLoading) {
+            return k(createMemoizedStream(function* () {
+                if (Array.isArray(left))
+                    yield* left;
+                else if (typeof left === "string")
+                    yield* left.split("");
+                else if (isLazyList(left))
+                    yield* left.generator();
+                else
+                    throw new Error("Invalid left operand for lazy Concat");
+                if (Array.isArray(right))
+                    yield* right;
+                else if (typeof right === "string")
+                    yield* right.split("");
+                else if (isLazyList(right))
+                    yield* right.generator();
+                else
+                    throw new Error("Invalid right operand for lazy Concat");
+            }));
+        }
+        if (typeof left === "string" && typeof right === "string")
+            return k(left + right);
+        return this.realizeList(left, (lArr) => {
+            return () => this.realizeList(right, (rArr) => {
+                return k(lArr.concat(rArr));
+            });
+        });
+    }
+    evaluateConcatLazy(node, evaluator, k) {
+        const ctx = this.context;
+        return evaluator.evaluate(node.left, (left) => {
+            const capturedEnv = ctx.clone();
+            return k(createMemoizedStream(function* () {
+                if (Array.isArray(left))
+                    yield* left;
+                else if (typeof left === "string")
+                    yield* left.split("");
+                else if (isLazyList(left))
+                    yield* left.generator();
+                else
+                    throw new Error("Invalid left operand for lazy Concat");
+                // right evaluates lazily on demand
+                const prevEnv = ctx.env;
+                ctx.setEnv(capturedEnv);
+                let right;
+                try {
+                    right = trampoline(evaluator.evaluate(node.right, idContinuation));
+                }
+                finally {
+                    ctx.setEnv(prevEnv);
+                }
+                if (Array.isArray(right))
+                    yield* right;
+                else if (typeof right === "string")
+                    yield* right.split("");
+                else if (isLazyList(right))
+                    yield* right.generator();
+                else
+                    throw new Error("Invalid right operand for lazy Concat");
+            }));
+        });
+    }
+    deepEqual(a, b, k) {
+        if (a === b)
+            return k(true);
+        const aIsListLike = this.isListLike(a);
+        const bIsListLike = this.isListLike(b);
+        const eitherIsCollection = this.isCollection(a) || this.isCollection(b);
+        if (eitherIsCollection && aIsListLike && bIsListLike) {
+            return this.realizeList(a, (valA) => () => this.realizeList(b, (valB) => {
+                if (valA.length !== valB.length)
+                    return k(false);
+                return this.deepEqualCollection(valA, valB, 0, k);
+            }));
+        }
+        if (eitherIsCollection)
+            return k(false); // colección vs número → false
+        if (this.isPlainObject(a) && this.isPlainObject(b))
+            return this.deepEqualObject(a, b, k);
+        return k(a == b); // primitivos: number, boolean, string==number
+    }
+    isPlainObject(val) {
+        return val !== null && typeof val === "object"
+            && !isLazyList(val) && !Array.isArray(val);
+    }
+    isCollection(val) {
+        return Array.isArray(val) || isLazyList(val);
+    }
+    isListLike(val) {
+        return Array.isArray(val) || isLazyList(val) || typeof val === "string";
+    }
+    deepEqualCollection(a, b, index, k) {
+        if (index >= a.length)
+            return k(true);
+        return this.deepEqual(a[index], b[index], (eq) => {
+            if (!eq)
+                return k(false);
+            return () => this.deepEqualCollection(a, b, index + 1, k);
+        });
+    }
+    deepEqualObject(a, b, k) {
+        const keys = Object.keys(a);
+        if (keys.length !== Object.keys(b).length)
+            return k(false);
+        const checkNext = (index) => {
+            if (index >= keys.length)
+                return k(true);
+            const key = keys[index];
+            return this.deepEqual(a[key], b[key], (eq) => {
+                if (!eq)
+                    return k(false);
+                return () => checkNext(index + 1);
+            });
+        };
+        return checkNext(0);
+    }
+}

package/dist/src/interpreter/components/runtimes/ObjectRuntime.d.ts

@@ -0,0 +1,35 @@
+import { PrimitiveValue, RuntimeFunction, RuntimeObject, EnvStack } from "yukigo-ast";
+import { Continuation, Thunk } from "../../trampoline.js";
+import { RuntimeContext } from "../RuntimeContext.js";
+export declare class ObjectRuntime {
+    private context;
+    constructor(context: RuntimeContext);
+    /**
+     * Creates a new instance of an Object.
+     * Typically called by visitNew()
+     */
+    instantiate(className: string, identifier: string, fieldDefinitions: Map<string, PrimitiveValue>, methodDefinitions: Map<string, RuntimeFunction>): RuntimeObject;
+    /**
+     * Handles Method Calls (Message Passing).
+     * Reuses FunctionRuntime to execute the method body.
+     */
+    dispatch(receiver: PrimitiveValue, methodName: string, args: PrimitiveValue[], env: EnvStack, k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    /**
+     * Handles calls to super() or super.method()
+     */
+    dispatchSuper(currentEnv: EnvStack, methodName: string, args: PrimitiveValue[], k: Continuation<PrimitiveValue>): Thunk<PrimitiveValue>;
+    private createDispatchScope;
+    private getResolutionChain;
+    private expandClassHierarchy;
+    private findMethodInChain;
+    /**
+     * Field Access (Get)
+     * e.g. self.myField
+     */
+    getField(receiver: PrimitiveValue, fieldName: string): PrimitiveValue;
+    /**
+     * Field Mutation (Set)
+     * e.g. self.myField = 10
+     */
+    setField(receiver: PrimitiveValue, fieldName: string, value: PrimitiveValue): PrimitiveValue;
+}

package/dist/src/interpreter/components/runtimes/ObjectRuntime.js

@@ -0,0 +1,126 @@
+import { isRuntimeObject, isRuntimeClass, } from "yukigo-ast";
+import { InterpreterError } from "../../errors.js";
+export class ObjectRuntime {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Creates a new instance of an Object.
+     * Typically called by visitNew()
+     */
+    instantiate(className, identifier, fieldDefinitions, methodDefinitions) {
+        return {
+            type: "Object",
+            className,
+            identifier,
+            fields: new Map(fieldDefinitions),
+            methods: methodDefinitions,
+        };
+    }
+    /**
+     * Handles Method Calls (Message Passing).
+     * Reuses FunctionRuntime to execute the method body.
+     */
+    dispatch(receiver, methodName, args, env, k) {
+        if (!isRuntimeObject(receiver))
+            throw new Error(`${receiver} is not an object`);
+        const chain = this.getResolutionChain(receiver, env);
+        const match = this.findMethodInChain(chain, methodName);
+        if (!match)
+            throw new InterpreterError("MethodDispatch", `${receiver.className} does not understand '${methodName}'.`);
+        const objectScope = this.createDispatchScope(receiver, match, methodName);
+        this.context.pushEnv(objectScope);
+        return this.context.funcRuntime.apply(match.method, args, k);
+    }
+    /**
+     * Handles calls to super() or super.method()
+     */
+    dispatchSuper(currentEnv, methodName, args, k) {
+        const self = this.context.lookup("self");
+        const currentHolder = this.context.lookup("__CONTEXT_CLASS__");
+        const currentMethodName = this.context.lookup("__METHOD_NAME__");
+        const targetMethodName = methodName || currentMethodName;
+        if (!self || !currentHolder)
+            throw new InterpreterError("SuperError", "'super' used outside of a method context");
+        const chain = this.getResolutionChain(self, currentEnv);
+        const currentIndex = chain.findIndex((c) => c === currentHolder);
+        if (currentIndex === -1)
+            throw new Error("Fatal: Execution context not found in hierarchy chain");
+        const remainingChain = chain.slice(currentIndex + 1);
+        const match = this.findMethodInChain(remainingChain, methodName);
+        if (!match)
+            throw new InterpreterError("Super", `Super method '${methodName}' not found`);
+        const objectScope = this.createDispatchScope(self, match, targetMethodName);
+        this.context.pushEnv(objectScope);
+        return this.context.funcRuntime.apply(match.method, args, k);
+    }
+    createDispatchScope(self, match, targetName) {
+        const objectScope = new Map();
+        objectScope.set("self", self);
+        objectScope.set("__CONTEXT_CLASS__", match.holder);
+        objectScope.set("__METHOD_NAME__", targetName);
+        for (const [key, val] of self.fields)
+            objectScope.set(key, val);
+        return objectScope;
+    }
+    getResolutionChain(receiver, env) {
+        const chain = [];
+        chain.push(receiver);
+        if (receiver.className) {
+            this.expandClassHierarchy(receiver.className, env, chain);
+        }
+        return chain;
+    }
+    expandClassHierarchy(className, env, chain) {
+        const classDef = this.context.lookup(className);
+        if (!isRuntimeClass(classDef))
+            throw new InterpreterError("expandClassHierarchy", "classDef was expected to be a RuntimeClass");
+        chain.push(classDef);
+        const classDefCopy = [...classDef.mixins];
+        if (classDef.mixins)
+            classDefCopy.reverse().forEach((mixinName) => {
+                this.expandClassHierarchy(mixinName, env, chain);
+            });
+        if (classDef.superclass)
+            this.expandClassHierarchy(classDef.superclass, env, chain);
+    }
+    findMethodInChain(chain, methodName) {
+        for (const link of chain) {
+            if (link.methods.has(methodName))
+                return {
+                    method: link.methods.get(methodName),
+                    holder: link,
+                };
+        }
+        return undefined;
+    }
+    /**
+     * Field Access (Get)
+     * e.g. self.myField
+     */
+    getField(receiver, fieldName) {
+        if (!isRuntimeObject(receiver))
+            throw new InterpreterError("FieldAccess", "Target is not an object");
+        if (!receiver.fields.has(fieldName)) {
+            if (receiver.methods.has(fieldName))
+                return receiver.methods.get(fieldName);
+            throw new InterpreterError("FieldAccess", `Field '${fieldName}' not found in ${receiver.className}`);
+        }
+        return receiver.fields.get(fieldName);
+    }
+    /**
+     * Field Mutation (Set)
+     * e.g. self.myField = 10
+     */
+    setField(receiver, fieldName, value) {
+        if (!this.context.config.mutability)
+            throw new InterpreterError("FieldAssignment", `Cannot mutate field '${fieldName}': mutability is disabled`);
+        if (!isRuntimeObject(receiver))
+            throw new InterpreterError("FieldAssignment", "Target is not an object");
+        if (!receiver.fields.has(fieldName))
+            throw new InterpreterError("FieldAssignment", `Cannot set unknown field '${fieldName}'`);
+        receiver.fields.set(fieldName, value);
+        return value;
+    }
+}

package/dist/src/interpreter/errors.d.ts

@@ -0,0 +1,19 @@
+import { SourceLocation } from "yukigo-ast";
+export interface ErrorFrame {
+    nodeType: string;
+    loc?: SourceLocation;
+}
+export declare class InterpreterError extends Error {
+    context: string;
+    frames: ErrorFrame[];
+    constructor(context: string, message: string, frames?: ErrorFrame[]);
+    pushFrame(frame: ErrorFrame): void;
+    formatStack(): string;
+    toString(): string;
+}
+export declare class UnexpectedValue extends InterpreterError {
+    constructor(ctx: string, expected: string, got: string);
+}
+export declare class UnboundVariable extends Error {
+    constructor(name: string);
+}

package/dist/src/interpreter/errors.js

@@ -0,0 +1,36 @@
+export class InterpreterError extends Error {
+    context;
+    frames;
+    constructor(context, message, frames = []) {
+        super(`[${context}] ${message}`);
+        this.context = context;
+        this.frames = frames;
+    }
+    pushFrame(frame) {
+        this.frames.push(frame);
+    }
+    formatStack() {
+        if (!this.frames.length)
+            return "";
+        const formatted = this.frames
+            .map((f) => {
+            const loc = f.loc ? ` (line ${f.loc.line}, col ${f.loc.column})` : "";
+            return `  • ${f.nodeType}${loc}`;
+        })
+            .join("\n");
+        return `\nTrace:\n${formatted}`;
+    }
+    toString() {
+        return `${this.message}${this.formatStack()}`;
+    }
+}
+export class UnexpectedValue extends InterpreterError {
+    constructor(ctx, expected, got) {
+        super(ctx, `Expected ${expected} but got ${got}`);
+    }
+}
+export class UnboundVariable extends Error {
+    constructor(name) {
+        super(`Unbound variable: ${name}`);
+    }
+}

package/dist/src/interpreter/index.d.ts

@@ -0,0 +1,24 @@
+import { PrimitiveValue, AST, ASTNode } from "yukigo-ast";
+import { InterpreterConfig } from "./components/RuntimeContext.js";
+export type Bindings = [string, PrimitiveValue][];
+/**
+ * The Interpreter class is responsible for evaluating the Abstract Syntax Tree (AST)
+ * generated by the parsers.
+ *
+ * It manages the global execution environment and delegates the actual evaluation
+ * of Expression nodes to a dedicated visitor.
+ */
+export declare class Interpreter {
+    private context;
+    /**
+     * @param ast The Abstract Syntax Tree (AST) of the program to be interpreted.
+     */
+    constructor(ast: AST, config?: InterpreterConfig);
+    /**
+     * Evaluates a single Expression node within the context of the global environment.
+     *
+     * @param expr The root Expression node to be evaluated.
+     * @returns The resulting primitive value (number, string, boolean, etc.) after evaluation.
+     */
+    evaluate(expr: ASTNode): PrimitiveValue;
+}