yukigo 0.1.0

package/dist/interpreter/index.js

@@ -0,0 +1,44 @@
+import { InterpreterVisitor } from "./components/Visitor.js";
+import { EnvBuilderVisitor } from "./components/EnvBuilder.js";
+import { InterpreterError } from "./errors.js";
+const DefaultConfiguration = {
+    lazyLoading: false,
+    debug: false,
+    outputMode: "first",
+};
+/**
+ * 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 class Interpreter {
+    globalEnv;
+    config;
+    /**
+     * @param ast The Abstract Syntax Tree (AST) of the program to be interpreted.
+     */
+    constructor(ast, config) {
+        this.globalEnv = new EnvBuilderVisitor().build(ast);
+        this.config = config ?? DefaultConfiguration;
+    }
+    /**
+     * 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) {
+        try {
+            const visitor = new InterpreterVisitor(this.globalEnv, this.config);
+            const evaluatedExpr = expr.accept(visitor);
+            return evaluatedExpr;
+        }
+        catch (error) {
+            if (error instanceof InterpreterError)
+                console.log(error.formatStack());
+            throw error;
+        }
+    }
+}

package/dist/interpreter/utils.d.ts

@@ -0,0 +1,14 @@
+import { Expression, LazyList, PrimitiveValue } from "@yukigo/ast";
+import { Environment, EnvStack } from "./index.js";
+export interface ExpressionEvaluator {
+    evaluate(node: Expression): PrimitiveValue;
+}
+export declare function createStream(generator: () => Generator<PrimitiveValue, void, unknown>): LazyList;
+export declare function isArrayOfNumbers(arr: PrimitiveValue[]): arr is number[];
+export declare function generateRange(start: number, end: number, step: number): number[];
+export declare function createEnv(bindings: [string, PrimitiveValue][]): Environment;
+export declare function createGlobalEnv(): EnvStack;
+export declare function pushEnv(env: EnvStack, frame?: Environment): EnvStack;
+export declare function popEnv(env: EnvStack): EnvStack;
+export declare function lookup(env: EnvStack, name: string): PrimitiveValue;
+export declare function define(env: EnvStack, name: string, value: PrimitiveValue): void;

package/dist/interpreter/utils.js

@@ -0,0 +1,57 @@
+import { UnboundVariable } from "./errors.js";
+export function createStream(generator) {
+    return {
+        type: "LazyList",
+        generator,
+    };
+}
+export function isArrayOfNumbers(arr) {
+    for (const item of arr)
+        if (typeof item !== "number")
+            return false;
+    return true;
+}
+export function generateRange(start, end, step) {
+    if (step === 0)
+        throw new Error("Step cannot be zero in range expression");
+    const result = [];
+    let current = start;
+    if (step > 0) {
+        while (current <= end) {
+            result.push(current);
+            current += step;
+        }
+    }
+    else {
+        while (current >= end) {
+            result.push(current);
+            current += step;
+        }
+    }
+    return result;
+}
+export function createEnv(bindings) {
+    const env = new Map();
+    for (const [name, value] of bindings)
+        env.set(name, value);
+    return env;
+}
+export function createGlobalEnv() {
+    return [new Map()];
+}
+export function pushEnv(env, frame) {
+    return [frame ?? new Map(), ...env];
+}
+export function popEnv(env) {
+    return env.slice(1);
+}
+export function lookup(env, name) {
+    for (const frame of env) {
+        if (frame.has(name))
+            return frame.get(name);
+    }
+    throw new UnboundVariable(name);
+}
+export function define(env, name, value) {
+    env[0].set(name, value);
+}

package/dist/utils/helpers.d.ts

@@ -0,0 +1,14 @@
+import { InspectionRule } from "../analyzer/index.js";
+import { YukigoPrimitive } from "@yukigo/ast";
+/**
+ * Translates Mulang inspections (YAML format) to an array of `InspectionRule` objects.
+ * @param mulangYamlString The Mulang inspection syntax as a YAML string.
+ * @returns An array of InspectionRule objects.
+ */
+export declare class MulangAdapter {
+    translateMulangInspection(mulangInspection: any): InspectionRule;
+    translateMulangExpectations(mulangYamlString: string): InspectionRule[];
+}
+export declare const yukigoTsMappings: {
+    [key in YukigoPrimitive]: string;
+};

package/dist/utils/helpers.js

@@ -0,0 +1,51 @@
+import { parseDocument } from "yaml";
+/**
+ * Translates Mulang inspections (YAML format) to an array of `InspectionRule` objects.
+ * @param mulangYamlString The Mulang inspection syntax as a YAML string.
+ * @returns An array of InspectionRule objects.
+ */
+export class MulangAdapter {
+    translateMulangInspection(mulangInspection) {
+        if (!mulangInspection ||
+            typeof mulangInspection.inspection !== "string" ||
+            typeof mulangInspection.binding !== "string") {
+            throw Error(`Skipping malformed Mulang inspection entry: ${mulangInspection}`);
+        }
+        const inspection = mulangInspection.inspection.split(":");
+        const expected = inspection[0] !== "Not";
+        const args = inspection.slice(expected ? 1 : 2);
+        return {
+            inspection: expected ? inspection[0] : inspection[1],
+            expected,
+            args,
+            binding: mulangInspection.binding,
+        };
+    }
+    translateMulangExpectations(mulangYamlString) {
+        const parsedYaml = parseDocument(mulangYamlString).toJS();
+        if (!parsedYaml ||
+            !parsedYaml.expectations ||
+            !Array.isArray(parsedYaml.expectations)) {
+            throw Error("Invalid Mulang YAML structure. Expected 'expectations' to be an array.");
+        }
+        const inspectionRules = [];
+        for (const mulangInspection of parsedYaml.expectations) {
+            const inspection = this.translateMulangInspection(mulangInspection);
+            inspectionRules.push(inspection);
+        }
+        return inspectionRules;
+    }
+}
+export const yukigoTsMappings = {
+    YuNumber: "number",
+    YuString: "string",
+    YuChar: "char",
+    YuBoolean: "boolean",
+    YuNil: "null",
+    // Below some missing mappigs
+    YuList: "YuList",
+    YuObject: "YuObject",
+    YuDict: "YuDict",
+    YuTuple: "YuTuple",
+    YuSymbol: "YuSymbol",
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "yukigo",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "mocha --import=tsx"
+  },
+  "dependencies": {
+    "typescript": "^5.9.2",
+    "yaml": "^2.8.0",
+    "yukigo-ast": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.2.2",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.2.0",
+    "chai": "^6.2.0",
+    "mocha": "^11.7.1",
+    "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
+    "typescript-eslint": "^8.33.1"
+  }
+}

package/src/analyzer/index.ts

@@ -0,0 +1,132 @@
+import { AST } from "yukigo-ast";
+import { genericInspections } from "./inspections/generic.js";
+import { functionalInspections } from "./inspections/functional.js";
+import { logicInspections } from "./inspections/logic.js";
+import { objectInspections } from "./inspections/object.js";
+import { imperativeInspections } from "./inspections/imperative.js";
+import { InspectionHandler, InspectionMap } from "./utils.js";
+
+export type AnalysisResult = {
+  rule: InspectionRule;
+  passed: boolean;
+  actual: boolean;
+  error?: string;
+};
+
+export type InspectionRule = {
+  inspection: string;
+  binding?: string;
+  args: string[];
+  expected: boolean;
+};
+
+export const defaultInspectionSet: InspectionMap = {
+  ...genericInspections,
+  ...functionalInspections,
+  ...logicInspections,
+  ...objectInspections,
+  ...imperativeInspections,
+};
+
+/**
+ * The Analyzer class.
+ * @remarks
+ * The Analyzer is the part of Yukigo which runs the inspections on the AST.
+ */
+export class Analyzer {
+  /**
+   * The set of inspections that are available for the Analyzer.
+   * You can load your set of inspections or leave the default one.
+   * @defaultValue a default set of inspections for each supported paradigm
+   */
+  private inspectionHandlers: InspectionMap = {};
+  constructor(inspectionSet?: InspectionMap) {
+    this.inspectionHandlers = inspectionSet ?? defaultInspectionSet;
+  }
+
+  /**
+   * Registers a new custom inspection handler after Analyzer was instantiated.
+   * @param name The name of the inspection (e.g., "HasArithmetic").
+   * @param handler The function that implements the inspection logic.
+   *
+   * @example
+   * // Implementation of HasArithmetic inspection
+   * export class UsesArithmetic extends TraverseVisitor {
+   *  visitArithmeticBinaryOperation(node: ArithmeticBinaryOperation): void {
+   *    throw new StopTraversalException();
+   *  }
+   *  visitArithmeticUnaryOperation(node: ArithmeticUnaryOperation): void {
+   *    throw new StopTraversalException();
+   *  }
+   * }
+   * const analyzer = new ASTAnalyzer(ast);
+   * analyzer.registerInspection("HasArithmetic", (node, args) => executeVisitor(node, new UsesArithmetic()));
+   */
+  public registerInspection(name: string, handler: InspectionHandler) {
+    this.inspectionHandlers[name] = handler;
+  }
+
+  /**
+   * Runs a list of inspection rules against the AST.
+   * @param ast The parsed AST.
+   * @param rules The array of inspection rules to run.
+   * @returns An array of analysis results.
+   * @example
+   * const rules: InspectionRule[] = [
+   *  {
+   *    inspection: "HasBinding",
+   *    args: { name: "minimoEntre" },
+   *    expected: false,
+   *  },
+   *  {
+   *    inspection: "HasBinding",
+   *    args: { name: "squareList" },
+   *    expected: true,
+   *  }
+   * ]
+   * const analyzer = new ASTAnalyzer(ast);
+   * const analysisResults = analyzer.analyze(expectations);
+   */
+  public analyze(ast: AST, rules: InspectionRule[]): AnalysisResult[] {
+    const results: AnalysisResult[] = [];
+    for (const rule of rules) {
+      results.push(this.runRule(rule, ast));
+    }
+    return results;
+  }
+
+  private runRule(rule: InspectionRule, ast: AST): AnalysisResult {
+    const inspection = this.inspectionHandlers[rule.inspection];
+    if (!inspection)
+      return {
+        rule,
+        passed: false,
+        actual: false,
+        error: "Unknown inspection",
+      };
+
+    try {
+      let result = false;
+      for (const node of ast) {
+        if (inspection(node, rule.args, rule.binding)) {
+          result = true;
+          break;
+        }
+      }
+
+      const passed = result === rule.expected;
+      return {
+        rule,
+        passed,
+        actual: result,
+      };
+    } catch (error) {
+      return {
+        rule,
+        passed: false,
+        actual: false,
+        error,
+      };
+    }
+  }
+}

package/src/analyzer/inspections/functional.ts

@@ -0,0 +1,159 @@
+import {
+  ApplicationPattern,
+  AsPattern,
+  ASTNode,
+  CompositionExpression,
+  ConsPattern,
+  ConstructorPattern,
+  Fact,
+  For,
+  Function,
+  FunctorPattern,
+  GuardedBody,
+  Lambda,
+  ListComprehension,
+  ListPattern,
+  LiteralPattern,
+  Rule,
+  StopTraversalException,
+  TraverseVisitor,
+  TuplePattern,
+  UnionPattern,
+  WildcardPattern,
+  Yield,
+} from "yukigo-ast";
+import { InspectionMap, executeVisitor } from "../utils.js";
+
+export class FunctionVisitor extends TraverseVisitor {
+  private readonly targetBinding: string;
+  protected isInsideTargetScope: boolean = false; // this flag helps to check nested functions inside the targetBinding scope
+  constructor(binding: string) {
+    super();
+    this.targetBinding = binding;
+  }
+  visitFunction(node: Function): void {
+    const currentFunctionName = node.identifier.value;
+
+    // if not inside scope then is top-level
+    if (!this.isInsideTargetScope) {
+      if (!this.targetBinding || currentFunctionName === this.targetBinding) {
+        this.isInsideTargetScope = true;
+        this.traverseCollection(node.equations);
+        this.isInsideTargetScope = false;
+        return;
+      }
+      return;
+    }
+    // if inside the scope of targetBinding then traverse
+    this.traverseCollection(node.equations);
+  }
+}
+
+export class UsesComposition extends FunctionVisitor {
+  visitCompositionExpression(node: CompositionExpression): void {
+    throw new StopTraversalException();
+  }
+}
+export class UsesAnonymousVariable extends TraverseVisitor {
+  private readonly targetBinding: string;
+  protected isInsideTargetScope: boolean = false;
+
+  constructor(binding: string) {
+    super();
+    this.targetBinding = binding;
+  }
+
+  visitWildcardPattern(node: WildcardPattern): void {
+    throw new StopTraversalException();
+  }
+  visitFunction(node: Function): void {
+    this.enterScope(node, node.equations);
+  }
+  visitFact(node: Fact): void {
+    this.enterScope(node, node.patterns);
+  }
+  visitRule(node: Rule): void {
+    this.enterScope(node, node.patterns);
+  }
+  private enterScope(node: Function | Fact | Rule, children: ASTNode[]): void {
+    const nodeName = node.identifier.value;
+    if (!this.isInsideTargetScope) {
+      if (!this.targetBinding || nodeName === this.targetBinding) {
+        this.isInsideTargetScope = true;
+        this.traverseCollection(children);
+        this.isInsideTargetScope = false;
+      }
+      return;
+    }
+    this.traverseCollection(children);
+  }
+}
+export class UsesComprehension extends FunctionVisitor {
+  visitListComprehension(node: ListComprehension): void {
+    throw new StopTraversalException();
+  }
+}
+export class UsesGuards extends FunctionVisitor {
+  visitGuardedBody(node: GuardedBody): void {
+    throw new StopTraversalException();
+  }
+}
+export class UsesLambda extends FunctionVisitor {
+  visitLambda(node: Lambda): void {
+    throw new StopTraversalException();
+  }
+}
+export class UsesYield extends FunctionVisitor {
+  visitYield(node: Yield): void {
+    throw new StopTraversalException();
+  }
+}
+export class UsesPatternMatching extends FunctionVisitor {
+  visitConsPattern(node: ConsPattern): void {
+    throw new StopTraversalException();
+  }
+  visitAsPattern(node: AsPattern): void {
+    throw new StopTraversalException();
+  }
+  visitListPattern(node: ListPattern): void {
+    throw new StopTraversalException();
+  }
+  visitTuplePattern(node: TuplePattern): void {
+    throw new StopTraversalException();
+  }
+  visitLiteralPattern(node: LiteralPattern): void {
+    throw new StopTraversalException();
+  }
+  visitApplicationPattern(node: ApplicationPattern): void {
+    throw new StopTraversalException();
+  }
+  visitConstructorPattern(node: ConstructorPattern): void {
+    throw new StopTraversalException();
+  }
+  visitUnionPattern(node: UnionPattern): void {
+    throw new StopTraversalException();
+  }
+  visitFunctorPattern(node: FunctorPattern): void {
+    throw new StopTraversalException();
+  }
+  visitWildcardPattern(node: WildcardPattern): void {
+    throw new StopTraversalException();
+  }
+}
+
+export const functionalInspections: InspectionMap = {
+  UsesComposition: (node, args, binding) =>
+    executeVisitor(node, new UsesComposition(binding)),
+  UsesAnonymousVariable: (node, args, binding) =>
+    executeVisitor(node, new UsesAnonymousVariable(binding)),
+  UsesComprehension: (node, args, binding) =>
+    executeVisitor(node, new UsesComprehension(binding)),
+  UsesGuards: (node, args, binding) =>
+    executeVisitor(node, new UsesGuards(binding)),
+  UsesLambda: (node, args, binding) =>
+    executeVisitor(node, new UsesLambda(binding)),
+  UsesYield: (node, args, binding) =>
+    executeVisitor(node, new UsesYield(binding)),
+  UsesPatternMatching: (node, args, binding) =>
+    executeVisitor(node, new UsesPatternMatching(binding)),
+};