yukigo 0.1.0

package/.mocharc.json

@@ -0,0 +1,4 @@
+{
+  "extension": ["ts"],
+  "spec": "tests/**/*.spec.ts"
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.1.0 (2025-12-09)
+
+### 🧱 Updated Dependencies
+
+- Updated yukigo-prolog-parser to 0.1.0
+- Updated yukigo-ast to 0.1.0

package/README.md

@@ -0,0 +1,199 @@
+# ❄️ Yukigo (WIP)
+A universal, multi-language, multi-paradigm code analyzer highly inspired in [mulang](https://github.com/mumuki/mulang)
+
+> [!WARNING]
+> This project is still in a "work in progress" state. Everything is subject to change :)
+
+
+## Components
+
+### **Abstract Semantic Tree:**
+
+This is the intermediate representation of any language. Allows us to analyse the semantics of the code independently of the paradigm or the language.
+
+### **Inspector:**
+
+We provide a set of built-in expectations for analysing code. Also allows to define custom expectations at runtime.
+
+### **Translator:**
+
+Translation AST-to-Typescript, this allows us to have an equivalent code to run input-output tests everywhere.
+
+### **Tester:**
+
+Runs tests for the Typescript translated code on an isolated enviroment.
+
+# Usage
+
+## Installation
+
+We will be using Haskell as the target language in this example.
+
+```
+npm install yukigo yukigo-haskell-parser
+```
+
+or
+
+```
+yarn add yukigo yukigo-haskell-parser
+```
+
+## Example
+
+```ts
+import { ASTAnalyzer } from "yukigo";
+import { YukigoHaskellParser } from "yukigo-haskell-parser";
+
+const code = "doble num = num * 2";
+const expectations = [
+  {
+    inspection: "HasBinding",
+    args: { name: "minimoEntre" },
+    expected: false,
+  },
+  {
+    inspection: "HasBinding",
+    args: { name: "doble" },
+    expected: true,
+  },
+];
+
+const parser = new YukigoHaskellParser();
+const ast = parser.parse(code);
+
+const analyser = new ASTAnalyzer(ast);
+const result = analyser.analyse(expectations);
+
+console.log(results);
+// [
+//   {
+//     rule: {
+//       inspection: "HasBinding",
+//       args: { name: "minimoEntre" },
+//       expected: false,
+//     },
+//     passed: true,
+//     actual: false,
+//   },
+//   {
+//     rule: {
+//       inspection: "HasBinding",
+//       args: { name: "doble" },
+//       expected: true,
+//     },
+//     passed: true,
+//     actual: true,
+//   },
+// ];
+```
+
+## Example with Mulang's Inspections (in a YAML file)
+
+```ts
+import { ASTAnalyzer, translateMulangToInspectionRules } from "yukigo";
+import { YukigoHaskellParser } from "yukigo-haskell-parser";
+
+const code = `
+squareList :: [Int] -> [Int]
+squareList xs = map (\n -> n * n) xs
+
+square :: Int -> Int
+square n = n * n
+
+squareList2 :: [Int] -> [Int]
+squareList2 = map square
+`;
+
+// Assuming the expectations are in a yaml file. Implement a way to load the actual file.
+const mulangInspections = `
+expectations:
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: squareList
+  inspection: HasBinding
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: squareList
+  inspection: HasLambdaExpression
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: square
+  inspection: HasArithmetic
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: doble
+  inspection: Not:HasBinding
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: square
+  inspection: Uses:n
+- !ruby/hash:ActiveSupport::HashWithIndifferentAccess
+  binding: squareList2
+  inspection: Uses:map
+`;
+
+const expectations = translateMulangToInspectionRules(mulangInspections);
+
+const parser = new YukigoHaskellParser();
+const ast = parser.parse(code);
+
+const analyser = new ASTAnalyzer(ast);
+const result = analyser.analyse(expectations);
+
+console.log(results);
+// [
+//   {
+//     rule: { inspection: "HasBinding", args: [Object], expected: true },
+//     passed: true,
+//     actual: true,
+//   },
+//   {
+//     rule: {
+//       inspection: "HasLambdaExpression",
+//       args: [Object],
+//       expected: true,
+//     },
+//     passed: true,
+//     actual: true,
+//   },
+//   {
+//     rule: { inspection: "HasArithmetic", args: [Object], expected: true },
+//     passed: true,
+//     actual: true,
+//   },
+//   {
+//     rule: { inspection: "HasBinding", args: [Object], expected: false },
+//     passed: true,
+//     actual: false,
+//   },
+//   {
+//     rule: { inspection: "Uses", args: [Object], expected: true },
+//     passed: true,
+//     actual: true,
+//   },
+//   {
+//     rule: { inspection: "Uses", args: [Object], expected: true },
+//     passed: true,
+//     actual: true,
+//   },
+// ];
+```
+
+# Relevant tools
+- yukigo-ast: A library of AST's node definitions
+  
+## Tools
+- [CLI](https://github.com/noiseArch/yukigo-cli)
+  
+## Parsers
+- Haskell
+- Prolog
+
+# How to make a parser
+
+A yukigo's parser is a class that implements the interface `YukigoParser` which exposes a public method called `parse` and an `errors` array like this:
+```ts
+errors: string[];
+parse: (code: string) => AST;
+```
+
+The package `yukigo-ast` has all the current supported AST nodes.
+For the grammar, you can use a tool like Jison or Nearley.
+
+Here's a tutorial for implementing a small custom language.

package/dist/analyzer/index.d.ts

@@ -0,0 +1,71 @@
+import { AST } from "@yukigo/ast";
+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 declare const defaultInspectionSet: InspectionMap;
+/**
+ * The Analyzer class.
+ * @remarks
+ * The Analyzer is the part of Yukigo which runs the inspections on the AST.
+ */
+export declare 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;
+    constructor(inspectionSet?: InspectionMap);
+    /**
+     * 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()));
+     */
+    registerInspection(name: string, handler: InspectionHandler): void;
+    /**
+     * 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);
+     */
+    analyze(ast: AST, rules: InspectionRule[]): AnalysisResult[];
+    private runRule;
+}

package/dist/analyzer/index.js

@@ -0,0 +1,110 @@
+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";
+export const defaultInspectionSet = {
+    ...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
+     */
+    inspectionHandlers = {};
+    constructor(inspectionSet) {
+        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()));
+     */
+    registerInspection(name, handler) {
+        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);
+     */
+    analyze(ast, rules) {
+        const results = [];
+        for (const rule of rules) {
+            results.push(this.runRule(rule, ast));
+        }
+        return results;
+    }
+    runRule(rule, ast) {
+        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/dist/analyzer/inspections/functional.d.ts

@@ -0,0 +1,46 @@
+import { ApplicationPattern, AsPattern, CompositionExpression, ConsPattern, ConstructorPattern, Fact, Function, FunctorPattern, GuardedBody, Lambda, ListComprehension, ListPattern, LiteralPattern, Rule, TraverseVisitor, TuplePattern, UnionPattern, WildcardPattern, Yield } from "@yukigo/ast";
+import { InspectionMap } from "../utils.js";
+export declare class FunctionVisitor extends TraverseVisitor {
+    private readonly targetBinding;
+    protected isInsideTargetScope: boolean;
+    constructor(binding: string);
+    visitFunction(node: Function): void;
+}
+export declare class UsesComposition extends FunctionVisitor {
+    visitCompositionExpression(node: CompositionExpression): void;
+}
+export declare class UsesAnonymousVariable extends TraverseVisitor {
+    private readonly targetBinding;
+    protected isInsideTargetScope: boolean;
+    constructor(binding: string);
+    visitWildcardPattern(node: WildcardPattern): void;
+    visitFunction(node: Function): void;
+    visitFact(node: Fact): void;
+    visitRule(node: Rule): void;
+    private enterScope;
+}
+export declare class UsesComprehension extends FunctionVisitor {
+    visitListComprehension(node: ListComprehension): void;
+}
+export declare class UsesGuards extends FunctionVisitor {
+    visitGuardedBody(node: GuardedBody): void;
+}
+export declare class UsesLambda extends FunctionVisitor {
+    visitLambda(node: Lambda): void;
+}
+export declare class UsesYield extends FunctionVisitor {
+    visitYield(node: Yield): void;
+}
+export declare class UsesPatternMatching extends FunctionVisitor {
+    visitConsPattern(node: ConsPattern): void;
+    visitAsPattern(node: AsPattern): void;
+    visitListPattern(node: ListPattern): void;
+    visitTuplePattern(node: TuplePattern): void;
+    visitLiteralPattern(node: LiteralPattern): void;
+    visitApplicationPattern(node: ApplicationPattern): void;
+    visitConstructorPattern(node: ConstructorPattern): void;
+    visitUnionPattern(node: UnionPattern): void;
+    visitFunctorPattern(node: FunctorPattern): void;
+    visitWildcardPattern(node: WildcardPattern): void;
+}
+export declare const functionalInspections: InspectionMap;

package/dist/analyzer/inspections/functional.js

@@ -0,0 +1,123 @@
+import { StopTraversalException, TraverseVisitor, } from "@yukigo/ast";
+import { executeVisitor } from "../utils.js";
+export class FunctionVisitor extends TraverseVisitor {
+    targetBinding;
+    isInsideTargetScope = false; // this flag helps to check nested functions inside the targetBinding scope
+    constructor(binding) {
+        super();
+        this.targetBinding = binding;
+    }
+    visitFunction(node) {
+        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) {
+        throw new StopTraversalException();
+    }
+}
+export class UsesAnonymousVariable extends TraverseVisitor {
+    targetBinding;
+    isInsideTargetScope = false;
+    constructor(binding) {
+        super();
+        this.targetBinding = binding;
+    }
+    visitWildcardPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitFunction(node) {
+        this.enterScope(node, node.equations);
+    }
+    visitFact(node) {
+        this.enterScope(node, node.patterns);
+    }
+    visitRule(node) {
+        this.enterScope(node, node.patterns);
+    }
+    enterScope(node, children) {
+        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) {
+        throw new StopTraversalException();
+    }
+}
+export class UsesGuards extends FunctionVisitor {
+    visitGuardedBody(node) {
+        throw new StopTraversalException();
+    }
+}
+export class UsesLambda extends FunctionVisitor {
+    visitLambda(node) {
+        throw new StopTraversalException();
+    }
+}
+export class UsesYield extends FunctionVisitor {
+    visitYield(node) {
+        throw new StopTraversalException();
+    }
+}
+export class UsesPatternMatching extends FunctionVisitor {
+    visitConsPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitAsPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitListPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitTuplePattern(node) {
+        throw new StopTraversalException();
+    }
+    visitLiteralPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitApplicationPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitConstructorPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitUnionPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitFunctorPattern(node) {
+        throw new StopTraversalException();
+    }
+    visitWildcardPattern(node) {
+        throw new StopTraversalException();
+    }
+}
+export const functionalInspections = {
+    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)),
+};