Release version 1.6.1

Author: alessiostalla

CHANGELOG.md

@@ -2,6 +2,15 @@
 All notable changes to this project from version 1.2.0 upwards are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
+## [1.6.1] – 2024-02-28
+
+### Added
+- Proper export of the Lionweb interop module
+- Module documentation for all optional interop modules
+
+### Removed
+- Deprecated AST transformation functions and decorators, that had been superseded by StarLasu AST Transformers.
+
 ## [1.6.0] – 2024-02-28
 
 ## Added

jest.config.js

@@ -18,10 +18,10 @@ const config = {
   coverageThreshold: {
     // Note: we have several deprecated functions that reduce coverage
     global: {
-      statements: 88,
+      statements: 90,
       branches: 84,
-      functions: 76, // Note: our CI on Node 16 computes a lower number for functions, for some reason
-      lines: 88,
+      functions: 80,
+      lines: 90,
     },
   },
   moduleDirectories: ["node_modules"],

package.json

@@ -3,7 +3,7 @@
 	"description": "AST building blocks for TypeScript/JavaScript, part of the *lasu family, with optional integrations with ANTLR4 and Ecore.",
 	"author": "Strumenta s.r.l.",
 	"publisher": "strumenta",
-	"version": "1.6.0",
+	"version": "1.6.1",
 	"license": "Apache-2.0",
 	"keywords": [
 		"antlr",
@@ -49,6 +49,11 @@
 			"require": "./dist/cjs/interop/ecore-enabled-parser.js",
 			"types": "./dist/types/interop/ecore-enabled-parser.d.ts"
 		},
+		"./interop/lionweb": {
+			"import": "./dist/esm/interop/lionweb.js",
+			"require": "./dist/cjs/interop/lionweb.js",
+			"types": "./dist/types/interop/lionweb.d.ts"
+		},
 		"./interop/strumenta-playground": {
 			"import": "./dist/esm/interop/strumenta-playground.js",
 			"require": "./dist/cjs/interop/strumenta-playground.js",
@@ -57,21 +62,12 @@
 	},
 	"typesVersions": {
 		"*": {
-			"parsing": [
-				"dist/types/parsing/index.d.ts"
-			],
-			"mapping": [
-				"dist/types/mapping.d.ts"
-			],
-			"interop/ecore": [
-				"dist/types/interop/ecore.d.ts"
-			],
-			"interop/ecore-enabled-parser": [
-				"dist/types/interop/ecore-enabled-parser.d.ts"
-			],
-			"interop/strumenta-playground": [
-				"dist/types/interop/strumenta-playground.d.ts"
-			]
+			"parsing": ["dist/types/parsing/index.d.ts"],
+			"mapping": ["dist/types/mapping.d.ts"],
+			"interop/ecore": ["dist/types/interop/ecore.d.ts"],
+			"interop/lionweb": ["dist/types/interop/lionweb.d.ts"],
+			"interop/ecore-enabled-parser": ["dist/types/interop/ecore-enabled-parser.d.ts"],
+			"interop/strumenta-playground": ["dist/types/interop/strumenta-playground.d.ts"]
 		}
 	},
 	"browser": "dist/esm/index.js",
@@ -107,7 +103,7 @@
 		"build": "yarn run build:esm && yarn run build:cjs",
 		"build:esm": "tsc --module es6 --outDir dist/esm",
 		"build:cjs": "tsc --module commonjs --outDir dist/cjs",
-		"extract-docs": "typedoc --out dist/docs src/index.ts src/parsing/index.ts src/mapping.ts src/interop/ecore.ts src/interop/ecore-enabled-parser.ts",
+		"extract-docs": "typedoc --out dist/docs src/index.ts src/parsing/index.ts src/mapping.ts src/interop/ecore.ts src/interop/ecore-enabled-parser.ts src/interop/lionweb.ts",
 		"lint": "eslint src tests",
 		"build-test-parser": "antlr4ng -Dlanguage=TypeScript -o tests/parser -Xexact-output-dir -visitor tests/grammar/SimpleLangLexer.g4 tests/grammar/SimpleLangParser.g4",
 		"test": "yarn run build-test-parser && node --experimental-vm-modules node_modules/jest/bin/jest.js",

src/interop/antlr4.ts

@@ -1,3 +1,7 @@
+/**
+ * ANTLR4 interoperability module. Requires the antlr4ng implementation.
+ * @module interop/antlr4
+ */
 export * from '../parsing/parse-tree';
 export * from '../parsing/parsing';
 export * from "../mapping";

src/interop/ecore.ts

@@ -1,3 +1,7 @@
+/**
+ * ECore interoperability module with ecore.js.
+ * @module interop/ecore
+ */
 import {
     ensureNodeDefinition,
     ensurePackage,

src/interop/lionweb.ts

@@ -1,3 +1,7 @@
+/**
+ * Lionweb interoperability module.
+ * @module interop/lionweb
+ */
 import {
     Classifier,
     Containment, deserializeLanguages,

src/mapping.ts

@@ -1,49 +1,8 @@
-import {ParserRuleContext, ParseTree, TerminalNode} from "antlr4ng";
-import {Child, Node, NODE_DEFINITION_SYMBOL, Origin, registerNodeDefinition} from "./model/model";
-import {ASTTransformer, GenericNode, Mapped, registerNodeFactory, transform} from "./transformation/transformation";
+import {ParserRuleContext, TerminalNode} from "antlr4ng";
+import {Node, Origin} from "./model/model";
+import {ASTTransformer} from "./transformation/transformation";
 import {ParseTreeOrigin} from "./parsing";
 
-/**
- * Registers the decorated node as a target for transformation from the given `type`.
- *
- * Note: this will eventually be integrated with Kolasu-style transformers.
- * @param type the type of the source node to map to this node.
- * @deprecated please use StarLasu AST transformers.
- */
-export function ASTNodeFor<T extends ParseTree>(type: new (...args: any[]) => T) {
-    return function (target: new () => Node): void {
-        if(!target[NODE_DEFINITION_SYMBOL]) {
-            registerNodeDefinition(target);
-        }
-        registerNodeFactory(type, () => new target());
-    };
-}
-
-//-------//
-// toAST //
-//-------//
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function toAST(tree?: ParseTree | null, parent?: Node): Node | undefined {
-    if (tree == null)
-        tree = undefined;
-
-    const node = transform(tree, parent, toAST);
-    if(node && !node.origin) { //Give a chance to custom factories to set a different node
-        node.origin = new ParseTreeOrigin(tree);
-    }
-    return node;
-}
-
-export class GenericParseTreeNode extends GenericNode {
-    @Child()
-    @Mapped("children")
-    childNodes: GenericParseTreeNode[] = [];
-}
-
-registerNodeFactory(ParserRuleContext, () => new GenericParseTreeNode());
 
 /**
  * Implements a transformation from an ANTLR parse tree (the output of the parser) to an AST (a higher-level

src/transformation/transformation.ts

@@ -1,16 +1,13 @@
 import {
     ASTNode,
-    ensureNodeDefinition,
     getNodeDefinition,
     Node,
-    NODE_DEFINITION_SYMBOL, NodeDefinition,
+    NodeDefinition,
     Origin,
-    registerNodeDefinition,
-    registerNodeProperty
 } from "../model/model";
 import {Issue, IssueSeverity} from "../validation";
 import {Position} from "../model/position";
-import {ErrorNode, GenericErrorNode} from "../model/errors";
+import {GenericErrorNode} from "../model/errors";
 
 export class PropertyRef<Obj, Value> {
     constructor(
@@ -393,197 +390,10 @@ export class ASTTransformer {
     }
 }
 
-//-----------------------------------//
-// Factory and metadata registration //
-//-----------------------------------//
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export const NODE_FACTORY_SYMBOL = Symbol("nodeFactory");
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export const INIT_SYMBOL = Symbol("init");
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function registerNodeFactory<T>(type: new (...args: any[]) => T, factory: (tree: T) => Node): void {
-    type.prototype[NODE_FACTORY_SYMBOL] = factory;
-}
-
-/**
- * Marks a property of a node as mapped from a property of another node of a different name.
- * @deprecated to be removed, use ParseTreeToASTTranformer
- * @param type the source node's type.
- * @param propertyName the name of the target property.
- * @param path the path in the source node that will be mapped to the target property.
- */
-export function registerPropertyMapping<T extends Node>(
-    type: new (...args: any[]) => T, propertyName: string, path: string = propertyName): any {
-    const propInfo: any = registerNodeProperty(type, propertyName);
-    propInfo.path = path || propertyName;
-    return propInfo;
-}
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function registerInitializer<T extends Node>(type: new (...args: any[]) => T, methodName: string): void {
-    type[INIT_SYMBOL] = methodName;
-}
-
-//------------//
-// Decorators //
-//------------//
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function NodeTransform<T extends Node>(type: new (...args: any[]) => T) {
-    return function (target: new () => Node): void {
-        if(!target[NODE_DEFINITION_SYMBOL]) {
-            registerNodeDefinition(target);
-        }
-        registerNodeFactory(type, () => new target());
-    };
-}
-
-/**
- * Marks a property of a node as mapped from a property of another node of a different name.
- * @deprecated to be removed, use ASTTranformer.withChild
- * @param path the path in the source node that will be mapped to the target property.
- */
-export function Mapped(path?: string): (target, methodName: string) => void {
-    return function (target, methodName: string) {
-        registerPropertyMapping(target, methodName, path);
-    };
-}
-
-/**
- * Decorator to register an initializer method on a Node. When a node is instantiated as the target of a
- * transformation, after its properties have been set, the transformer calls the init method, if any.
- * @param target the target type.
- * @param methodName the name of the init method.
- * @deprecated please use StarLasu AST transformers.
- */
-// Since target is any-typed (see https://www.typescriptlang.org/docs/handbook/decorators.html),
-// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-export function Init(target, methodName: string): void {
-    registerInitializer(target, methodName);
-}
-
-//-----------------//
-// Transformations //
-//-----------------//
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function fillChildAST<FROM, TO extends Node>(
-    node: TO, property: string, tree: FROM | undefined, transformer: (node: FROM) => TO | undefined): TO[] {
-    const propDef: any = ensureNodeDefinition(node).properties[property];
-    const propertyPath = propDef.path || property;
-    if (propertyPath && propertyPath.length > 0) {
-        const path = propertyPath.split(".");
-        let error;
-        for (const segment in path) {
-            if (tree && (typeof(tree[path[segment]]) === "function")) {
-                try {
-                    tree = tree[path[segment]]();
-                } catch (e) {
-                    error = e;
-                    break;
-                }
-            } else if (tree && tree[path[segment]]) {
-                tree = tree[path[segment]];
-            } else {
-                tree = undefined;
-                break;
-            }
-        }
-        if(error) {
-            node[property] = new GenericErrorNode(error);
-        } else if (tree) {
-            if(propDef.child) {
-                if (Array.isArray(tree)) {
-                    node[property] = [];
-                    for (const i in tree) {
-                        node[property].push(transformer(tree[i])?.withParent(node));
-                    }
-                    return node[property];
-                } else {
-                    node[property] = transformer(tree)?.withParent(node);
-                    return [node[property]];
-                }
-            } else {
-                node[property] = tree;
-            }
-        }
-    }
-    return [];
-}
-
-function makeNode(factory, tree: unknown) {
-    try {
-        return factory(tree) as Node;
-    } catch (e) {
-        return new GenericErrorNode(e);
-    }
-}
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export function transform(tree: unknown, parent?: Node, transformer: typeof transform = transform): Node | undefined {
-    if (typeof tree !== "object" || !tree) {
-        return undefined;
-    }
-    const factory = tree[NODE_FACTORY_SYMBOL];
-    let node: Node;
-    if (factory) {
-        node = makeNode(factory, tree);
-        const def = getNodeDefinition(node);
-        if (def) {
-            for (const p in def.properties) {
-                fillChildAST(node, p, tree, transformer);
-            }
-        }
-        const initFunction = node[INIT_SYMBOL];
-        if (initFunction) {
-            try {
-                node[initFunction].call(node, tree);
-            } catch (e) {
-                node = new PartiallyInitializedNode(node, e);
-            }
-        }
-    } else {
-        node = new GenericNode();
-    }
-    return node.withParent(parent);
-}
-
 @ASTNode("com.strumenta.tylasu.transformation", "GenericNode")
 export class GenericNode extends Node {
     constructor(parent?: Node) {
         super();
         this.parent = parent;
     }
 }
-
-/**
- * @deprecated please use StarLasu AST transformers.
- */
-export class PartiallyInitializedNode extends Node implements ErrorNode {
-    message: string;
-
-    get position(): Position | undefined {
-        return this.node.position;
-    }
-
-    constructor(readonly node: Node, error: Error) {
-        super();
-        this.message = `Could not initialize node: ${error}`;
-    }
-}

tests/mapping.test.ts

@@ -1,6 +1,6 @@
 import {expect} from "chai";
 
-import {ASTTransformer, Child, GenericErrorNode, GenericNode, Mapped, Node, Position} from "../src";
+import {ASTTransformer, Child, GenericErrorNode, GenericNode, Node, Position} from "../src";
 import {SimpleLangLexer} from "./parser/SimpleLangLexer";
 import {CharStreams, CommonTokenStream, ParserRuleContext} from "antlr4ng";
 import {CompilationUnitContext, DisplayStmtContext, SetStmtContext, SimpleLangParser} from "./parser/SimpleLangParser";