Add Visualization Tool

Lara-JS/package.json

@@ -21,7 +21,7 @@
     "tsconfig.json"
   ],
   "scripts": {
-    "build": "node scripts/copy-folder.js -i src-api/libs -o api/libs && npx tsc -b src-api src-code",
+    "build": "node scripts/copy-folder.js -i src-api/libs -o api/libs && node scripts/copy-folder.js -i src-api/visualization/public -o api/visualization/public && npx tsc -b src-api src-code",
     "build:api": "npx tsc -b src-api",
     "build:code": "npx tsc -b src-code",
     "build:watch": "npm run build -- --watch",
@@ -58,16 +58,20 @@
   "dependencies": {
     "chokidar": "^3.6.0",
     "debug": "^4.3.5",
+    "express": "^4.19.2",
     "java": "^0.14.0",
     "supports-color": "^9.4.0",
+    "ws": "^8.17.1",
     "yargs": "^17.7.2"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
     "@types/debug": "^4.1.12",
+    "@types/express": "^4.17.21",
     "@types/java": "^0.9.5",
     "@types/jest": "^29.5.12",
     "@types/node": "^20.14.10",
+    "@types/ws": "^8.5.11",
     "@types/yargs": "^17.0.32",
     "typescript-eslint": "^8.0.0-alpha.44",
     "cross-env": "^7.0.3",

Lara-JS/src-api/visualization/AstConverterUtils.ts

@@ -0,0 +1,64 @@
+/**
+ * @file AstConverterUtils.ts
+ * @brief Utility functions for the specializations of GenericAstConverter.
+ */
+
+/**
+ * @brief Adds indentation to the given code, with the exception of the first line.
+ * 
+ * @param code Code
+ * @param indentation The indentation to use 
+ * @returns The indented code
+ */
+const addIdentation = (code: string, indentation: number): string => {
+  return code.split('\n').map((line, i) => i > 0 ? '   '.repeat(indentation) + line : line).join('\n');
+};
+
+
+/**
+ * @brief Escapes the HTML special characters in the given text.
+ * 
+ * @param text Text to escape
+ * @returns The escaped text
+ */
+const escapeHtml = (text: string): string => {
+  const specialCharMap: { [char: string]: string } = {
+    '&': '&',
+    '<': '&lt;',
+    '>': '&gt;',
+  };
+
+  return text.replace(/[&<>]/g, (match) => specialCharMap[match]);
+};
+
+/**
+ * @brief Returns the opening and closing span tags with the given attributes.
+ * 
+ * @param attrs Attributes to add to the span tag
+ * @returns An array with the opening and closing span tags
+ */
+const getSpanTags = (...attrs: string[]): string[] => {
+  return [`<span ${attrs.join(' ')}>`, '</span>'];
+};
+
+/**
+ * @brief Returns the span tags for the code of the given node.
+ * 
+ * @param nodeId Node ID
+ * @returns An array with the opening and closing span tags
+ */
+const getNodeCodeTags = (nodeId: string): string[] => {
+  return getSpanTags('class="node-code"', `data-node-id="${nodeId}"`);
+};
+
+/**
+ * @brief Returns the span tags for syntax highlighting of code of the given type..
+ * 
+ * @param type Code type
+ * @returns An array with the opening and closing span tags
+ */
+const getSyntaxHighlightTags = (type: 'comment' | 'keyword' | 'literal' | 'string' | 'type'): string[] => {
+  return getSpanTags(`class="${type}"`);
+};
+
+export { addIdentation, escapeHtml, getSpanTags, getNodeCodeTags, getSyntaxHighlightTags };

Lara-JS/src-api/visualization/GenericAstConverter.ts

@@ -0,0 +1,41 @@
+import { LaraJoinPoint } from "../LaraJoinPoint.js";
+import ToolJoinPoint from "./public/js/ToolJoinPoint.js";
+
+/**
+ * @brief Object type for storing the code of each file
+ */
+export type FilesCode = {
+  [filepath: string]: string;
+};
+
+/**
+ * @brief Interface for the AST converter.
+ * @details This interface includes all the compiler specific operations that
+ * are required by the LARA visualization tool to work.
+ */
+export default interface GenericAstConverter {
+  /**
+   * @brief Updates/Rebuilds the AST on the compiler.
+   */
+  updateAst(): void;
+
+  /**
+   * @brief Converts the compiler AST joinpoints to ToolJoinPoint.
+   * 
+   * @param root Root of the AST
+   * @returns The AST converted to ToolJoinPoint
+   */
+  getToolAst(root: LaraJoinPoint): ToolJoinPoint; 
+
+  /**
+   * @brief Converts the compiled code to HTML code.
+   * @details This method should perform the mapping of each AST joinpoint to
+   * their respective code, using HTML tags, and optionally its syntax
+   * highlighting. See the getNodeCodeTags and getSyntaxHighlightTags methods
+   * in AstConverterUtils.js for more information.
+   * 
+   * @param root Root of the AST
+   * @returns The HTML code
+   */
+  getPrettyHtmlCode(root: LaraJoinPoint): FilesCode;
+}

Lara-JS/src-api/visualization/GenericVisualizationTool.ts

@@ -0,0 +1,218 @@
+import express from 'express';
+import http from 'http';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import WebSocket, { WebSocketServer } from 'ws';
+import { AddressInfo } from 'net';
+
+import { LaraJoinPoint } from '../LaraJoinPoint.js';
+import JoinPoints from '../weaver/JoinPoints.js';
+import GenericAstConverter, { FilesCode } from './GenericAstConverter.js';
+import ToolJoinPoint from './public/js/ToolJoinPoint.js';
+
+/**
+ * @brief Abstract class for a the LARA visualization tool.
+ * @details To use this class in a compiler, this class must be extended and
+ * the getAstConverter method must be implemented, returning the compiler
+ * specialization of the GenericAstConverter class.
+ */
+export default abstract class GenericVisualizationTool {
+  #hostname: string | undefined;
+  #port: number | undefined;
+  #wss: WebSocketServer | undefined;
+  #serverClosed: boolean = false;
+  #toolAst: ToolJoinPoint | undefined;
+  #prettyHtmlCode: FilesCode | undefined;
+
+  /**
+   * @brief True whether the visualization tool is launched, and false otherwise
+   */
+  public get isLaunched(): boolean {
+    return this.#wss !== undefined && this.#serverClosed === false;
+  }
+
+  /**
+   * @brief Hostname to which the visualization tool is listening to.
+   */
+  public get hostname(): string | undefined {
+    return this.#hostname;
+  }
+
+  /**
+   * @brief Port to which the visualization tool is listening to.
+   */
+  public get port(): number | undefined {
+    return this.#port;
+  }
+
+  /**
+   * @brief URL to which the visualization tool is listening to.
+   */
+  public get url(): string | undefined {
+    return this.#hostname && this.#port ? `http://${this.#hostname}:${this.#port}` : undefined;
+  }
+
+  /**
+   * @brief Updates the stored tool AST and code with the info retrieved from the astConverter.
+   * 
+   * @param astRoot The root of the wanted AST
+   */
+  private updateAstAndCode(astRoot: LaraJoinPoint): void {
+    const astConverter = this.getAstConverter();
+    astConverter.updateAst();
+
+    this.#toolAst = astConverter.getToolAst(astRoot);
+    this.#prettyHtmlCode = astConverter.getPrettyHtmlCode(astRoot);
+  }
+
+  /**
+   * @brief WebSocket server error handler.
+   * 
+   * @param error The error that occurred
+   */
+  private onWssError(error: NodeJS.ErrnoException): void {
+    switch (error.code) {
+      case 'EADDRINUSE':
+        console.error(`[server]: Port ${this.#port} is already in use`);
+        break;
+
+      case 'EACCES':
+        console.error(`[server]: Permission denied to use port ${this.#port}`);
+        break;
+
+      default:
+        console.error(`[server]: Unknown error occurred: ${error.message}`);
+        break;
+    };
+
+    this.#wss!.close();
+  }
+
+  /**
+   * @brief Launches the visualization tool.
+   * 
+   * @param hostname The hostname to listen to
+   * @param port The port to listen to
+   */
+  private async launch(hostname: string, port: number): Promise<void> {
+    const app = express();
+    const server = http.createServer(app);
+    this.#wss = new WebSocketServer({ server: server });
+
+    const filename = fileURLToPath(import.meta.url);
+    const dirname = path.dirname(filename);
+    app.use(express.static(path.join(dirname, 'public')));
+
+    this.#wss.on('connection', ws => this.updateClient(ws));
+    this.#wss.on('close', () => { this.#serverClosed = true; });
+    this.#wss.on('error', error => this.onWssError(error));
+
+    return new Promise(res => {
+      server.listen(port, hostname, () => {
+        const addressInfo = server.address() as AddressInfo;
+        this.#hostname = addressInfo.address;
+        this.#port = addressInfo.port;
+        this.#serverClosed = false;
+
+        res();
+      });
+    });
+  }
+
+  /**
+   * @brief Sends a message to a specific client
+   * 
+   * @param ws Client WebSocket
+   * @param data Data to be sent
+   */
+  private sendToClient(ws: WebSocket, data: any): void {
+    ws.send(JSON.stringify(data));
+  }
+
+  /**
+   * @brief Sends a message to all the clients
+   * 
+   * @param data Message data
+   */
+  private sendToAllClients(data: any): void {
+    this.#wss!.clients.forEach(ws => this.sendToClient(ws, data));
+  }
+
+  /**
+   * @brief Updates the client with the current tool AST and code.
+   * 
+   * @param ws Client WebSocket
+   */
+  private updateClient(ws: WebSocket): void {
+    this.sendToClient(ws, {
+      message: 'update',
+      ast: this.#toolAst!.toJson(),
+      code: this.#prettyHtmlCode!,
+    });
+  }
+
+  /**
+   * @brief Updates all the clients with the current tool AST and code.
+   */
+  private updateAllClients(): void {
+    this.#wss!.clients.forEach(ws => this.updateClient(ws));
+  }
+
+  /**
+   * @brief Waits for the tool to be ready to receive the AST and code.
+   */
+  private async waitForTool(): Promise<void> {
+    return new Promise(res => {
+      let placeClientOnWait: (ws: WebSocket) => void;
+
+      const waitOnMessage = (message: string) => {
+        const data = JSON.parse(message);
+        if (data.message === 'continue') {
+          this.#wss!.clients.forEach(ws => {
+            this.#wss!.off('connection', placeClientOnWait);
+            ws.off('message', waitOnMessage);
+          });
+
+          this.sendToAllClients({ message: 'continue' });
+          res();
+        }
+      }
+
+      placeClientOnWait = (ws: WebSocket) => {
+        ws.on('message', waitOnMessage);
+        this.sendToClient(ws, { message: 'wait' });
+      }
+
+      this.#wss!.clients.forEach(placeClientOnWait);
+      this.#wss!.on('connection', placeClientOnWait);
+    });
+  }
+
+  /**
+   * @brief Visualizes the given AST.
+   * @details This function launches the visualization tool, if it is not
+   * already launched, and updates the web interface with the AST and code,
+   * otherwise. This can involve the recompilation of the code.
+   * 
+   * @param astRoot Root of the AST to be visualized
+   * @param port The port to listen to
+   * @param hostname The hostname to listen to
+   */
+  public async visualize(astRoot: LaraJoinPoint = JoinPoints.root(), port: number = 3000, hostname: string = '127.0.0.1'): Promise<void> {
+    this.updateAstAndCode(astRoot!);
+
+    if (!this.isLaunched) {
+      await this.launch(hostname, port);
+    } else {
+      this.updateAllClients();
+    }
+
+    console.log(`\nVisualization tool is running at ${this.url}\n`);
+    await this.waitForTool();
+  }
+
+  /**
+   * @brief Returns the compiler AST converter.
+   */
+  protected abstract getAstConverter(): GenericAstConverter;
+};

Lara-JS/src-api/visualization/README.md

@@ -0,0 +1,36 @@
+# LARA Visualization Tool
+
+Web tool for visualization and analysis of the AST and its source code.
+
+## Integration
+
+Internally, the tool follows a system for interaction with the compiler, to be able to apply code linkage and correction, among others, while still being independent of the specific compiler. This system is an implementation of the Factory Method pattern, and the integration with Clava is illustrated in the following diagram:
+
+![Compiler Abstracted System](./compiler-abstracted-system.svg)
+
+To integrate the tool in another compiler:
+
+1. Implement the `GenericAstConverter` interface, with its functions properly implemented. More information can be found in their documentation.
+2. Create a class that extends `GenericVisualizationTool`, and override `getAstConverter` so that it returns an instance of the class declared in the previous step.
+3. Use an instance of the previous class as the entry point of the visualization tool API, for the compiler in question.
+
+## Usage
+
+After integration, and being `VisualizationTool` the extended derived class of `GenericVisualizationTool`, to launch or update the visualization tool, execute the following statement:
+
+```js
+await VisualizationTool.visualize();
+```
+
+Once ready, Clava will provide the URL that should be opened in the browser to access the web interface. The function can also change the AST root and URL domain and port.
+
+Other properties will allow the user to know other important information from the server:
+
+```js
+VisualizationTool.isLaunched;  // true if the server is running
+VisualizationTool.url;         // URL where the server is running
+VisualizationTool.port;        // port to which the server is listening
+VisualizationTool.hostname;    // hostname to which the server is listening
+```
+
+For more details, refer to the `GenericVisualizationTool` documentation.