@mpeggroup/mpeg-sdl-parser 4.0.0

package/src/scanner-error.ts

@@ -0,0 +1,65 @@
+import type { Location } from "./location.ts";
+
+/**
+ * Base error class.
+ */
+export abstract class ScannerError extends Error {
+  protected constructor(
+    public errorMessage: string,
+    public location?: Location,
+  ) {
+    super(
+      errorMessage +
+        (location
+          ? ` => { row: ${location.row}, column: ${location.column}, position: ${location.position} }`
+          : ""),
+    );
+  }
+}
+
+/**
+ * Indicates an internal logic error in the scanner implementation.
+ */
+export class InternalScannerError extends ScannerError {
+  constructor(errorMessage: string, location?: Location) {
+    super(`INTERNAL SCANNER ERROR: ${errorMessage}`, location);
+  }
+}
+
+/**
+ * Indicates a syntactic error in the provided source.
+ */
+export class SyntaxError extends ScannerError {
+  constructor(
+    errorMessage: string,
+    location?: Location,
+    public errorLine?: string,
+    public precedingLines?: string[],
+  ) {
+    super(`SYNTAX ERROR: ${errorMessage}`.trim(), location);
+  }
+}
+
+/**
+ * Indicates a semantic error in the provided AST.
+ */
+export class SemanticError extends ScannerError {
+  constructor(
+    errorMessage: string,
+    location?: Location,
+  ) {
+    super(`SEMANTIC ERROR: ${errorMessage}`.trim(), location);
+  }
+}
+
+/**
+ * Indicates a semantic warning in the provided AST.
+ */
+export class SemanticWarning extends ScannerError {
+  constructor(
+    warningMessage: string,
+    location?: Location,
+  ) {
+    super(`SEMANTIC WARNING: ${warningMessage}`.trim(), location);
+  }
+}

package/src/util/location-utils.ts

@@ -0,0 +1,16 @@
+import { Text } from "@codemirror/state";
+import type { Location } from "../location.ts";
+
+export function getLocationFromTextPosition(
+  text: Text,
+  position: number,
+): Location {
+  const line = text.lineAt(position);
+  const row = line.number;
+  const column = position - line.from + 1;
+  return {
+    row,
+    column,
+    position,
+  };
+}

package/src/util/logger.ts

@@ -0,0 +1,165 @@
+declare global {
+  var defaultLogger: Logger | undefined;
+}
+
+type LoggerFunction = (
+  message: object | (() => string) | string,
+  ...optionalParams: unknown[]
+) => void;
+
+export interface Logger {
+  trace: LoggerFunction;
+  debug: LoggerFunction;
+  info: LoggerFunction;
+  warn: LoggerFunction;
+  error: LoggerFunction;
+}
+
+const LEVEL_PADDINGS: Record<string, string> = {
+  TRACE: "    ",
+  DEBUG: "    ",
+  INFO: "     ",
+  WARN: "     ",
+  ERROR: "    ",
+};
+
+export const debugEnabled = (() => {
+  // In a node-like environment, check for the environment variable.
+  if (typeof globalThis.process !== "undefined" && globalThis.process.env) {
+    return globalThis.process.env["MPEG_SDL_PARSER_DEBUG"] !== undefined;
+  }
+
+  // In a browser-like environment, check for the local storage item.
+  if (typeof localStorage !== "undefined") {
+    try {
+      return localStorage.getItem("MPEG_SDL_PARSER_DEBUG") !== null;
+    } catch (_e) {
+      // Ignore SecurityError if localStorage is disabled.
+      return false;
+    }
+  }
+  return false;
+})();
+
+let maxLoggerNameLength = 0;
+
+const LOGGER_NAME_PADDINGS: Record<string, string> = {};
+
+function getDefaultLogger(): Logger {
+  return {
+    trace: () => {},
+    debug: (message, ...optionalParams) => {
+      console.debug(message, ...optionalParams);
+    },
+    info: (message, ...optionalParams) => {
+      console.info(message, ...optionalParams);
+    },
+    warn: (message, ...optionalParams) => {
+      console.warn(message, ...optionalParams);
+    },
+    error: (message, ...optionalParams) => {
+      console.error(message, ...optionalParams);
+    },
+  };
+}
+
+function wrapDefaultLogger(
+  loggerName: string,
+  levelPadding: string,
+  loggerFunction: LoggerFunction,
+): LoggerFunction {
+  return (message, ...optionalParams) => {
+    if (message instanceof Function) {
+      loggerFunction(
+        `${levelPadding} [${loggerName}]${
+          LOGGER_NAME_PADDINGS[loggerName]
+        } ${message()}`,
+        ...optionalParams,
+      );
+      return;
+    }
+    if (message instanceof Object) {
+      loggerFunction(
+        `${levelPadding} [${loggerName}]${LOGGER_NAME_PADDINGS[loggerName]} ${
+          JSON.stringify(message)
+        }`,
+        ...optionalParams,
+      );
+      return;
+    }
+    loggerFunction(
+      `${levelPadding} [${loggerName}]${
+        LOGGER_NAME_PADDINGS[loggerName]
+      } ${message}`,
+      ...optionalParams,
+    );
+  };
+}
+
+/**
+ * Retrieves a logger instance with the specified name. If the name length exceeds the current maximum logger name length,
+ * it updates the padding for all existing logger names to ensure consistent formatting.
+ *
+ * @param loggerName The name of the logger to retrieve.
+ * @returns A logger instance with the specified name.
+ */
+export default function getLogger(loggerName: string): Logger {
+  if (globalThis.defaultLogger === undefined) {
+    globalThis.defaultLogger = getDefaultLogger();
+  }
+
+  if (loggerName.length > maxLoggerNameLength) {
+    maxLoggerNameLength = loggerName.length;
+
+    for (const key of Object.keys(LOGGER_NAME_PADDINGS)) {
+      LOGGER_NAME_PADDINGS[key] = " ".repeat(maxLoggerNameLength - key.length);
+    }
+
+    LOGGER_NAME_PADDINGS[loggerName] = "";
+  } else if (LOGGER_NAME_PADDINGS[loggerName] === undefined) {
+    LOGGER_NAME_PADDINGS[loggerName] = " ".repeat(
+      maxLoggerNameLength - loggerName.length,
+    );
+  }
+
+  if (debugEnabled) {
+    return {
+      trace: wrapDefaultLogger(
+        loggerName,
+        LEVEL_PADDINGS.TRACE,
+        globalThis.defaultLogger.trace,
+      ),
+      debug: wrapDefaultLogger(
+        loggerName,
+        LEVEL_PADDINGS.DEBUG,
+        globalThis.defaultLogger.debug,
+      ),
+      info: wrapDefaultLogger(
+        loggerName,
+        LEVEL_PADDINGS.INFO,
+        globalThis.defaultLogger.info,
+      ),
+      warn: wrapDefaultLogger(
+        loggerName,
+        LEVEL_PADDINGS.WARN,
+        globalThis.defaultLogger.warn,
+      ),
+      error: wrapDefaultLogger(
+        loggerName,
+        LEVEL_PADDINGS.ERROR,
+        globalThis.defaultLogger.error,
+      ),
+    };
+  }
+  return {
+    trace: () => {},
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: wrapDefaultLogger(
+      loggerName,
+      LEVEL_PADDINGS.ERROR,
+      globalThis.defaultLogger.error,
+    ),
+  };
+}

package/tests/analyser/create-sdl-analyser.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import {
+  createLenientSdlAnalyser,
+  createStrictSdlAnalyser,
+} from "../../src/analyser/create-sdl-analyser.ts";
+import { createLenientSdlParser } from "../../src/lezer/create-sdl-parser.ts";
+import { SdlStringInput } from "../../src/lezer/sdl-string-input.ts";
+import { buildAst } from "../../src/ast/build-ast.ts";
+import type { Specification } from "../../src/ast/node/specification.ts";
+
+const lenientSdlParser = createLenientSdlParser();
+
+function buildAstWithErrors() {
+  const sdlStringInput = new SdlStringInput(
+    "class A{bit transport_priority;}",
+  );
+  const parseTree = lenientSdlParser.parse(sdlStringInput);
+  const specification = buildAst(
+    parseTree,
+    sdlStringInput,
+    true,
+  );
+
+  return specification;
+}
+
+describe("createSdlAnalyser Tests", () => {
+  test("Test lenient SDL analyser creation", () => {
+    createLenientSdlAnalyser();
+  });
+
+  test("Test strict SDL analyser creation", () => {
+    createStrictSdlAnalyser();
+  });
+
+  test("Test lenient SDL analyser handles syntactic errors in parse tree", () => {
+    const specificationWithErrors = buildAstWithErrors();
+    const sdlAnalyser = createLenientSdlAnalyser();
+
+    // The lenient analyser should not throw an error
+    sdlAnalyser.analyse(specificationWithErrors as Specification);
+  });
+
+  test("Test strict SDL analyser throws on syntactic errors in parse tree", () => {
+    const specificationWithErrors = buildAstWithErrors();
+
+    const sdlAnalyser = createStrictSdlAnalyser();
+
+    expect(() => sdlAnalyser.analyse(specificationWithErrors as Specification))
+      .toThrow(
+        "SEMANTIC ERROR: Required identifier property is a Token node: ERROR_MISSING_TOKEN",
+      );
+  });
+});

package/tests/analyser/get-sdl-analyser-test-scenarios.ts

@@ -0,0 +1,80 @@
+function toLineContext(file: string, index: number): string {
+  const endEol = file.indexOf("\n", index + 80);
+  const endIndex = endEol === -1 ? file.length : endEol;
+
+  return file.substring(index, endIndex).split(/\n/).map((str) => "  | " + str)
+    .join("\n");
+}
+
+export interface TestScenario {
+  name: string;
+  text: string;
+  expected: string;
+  expectedErrors: string;
+  expectedWarnings: string;
+}
+
+export function getSdlAnalyserTestScenarios(file: string, fileName: string) {
+  const scenarioExpr =
+    /\s*#[ \t]*(.*)(?:\r\n|\r|\n)([^]*?)==+>([^]*?)(?:\s*$|(?:\r\n|\r|\n)+(?=#))/gy;
+  const testScenarios: Array<TestScenario> = [];
+  let lastIndex = 0;
+
+  for (;;) {
+    const scenarioRegexResult = scenarioExpr.exec(file);
+
+    if (!scenarioRegexResult) {
+      throw new Error(
+        `Unexpected file format in ${fileName} around\n\n${
+          toLineContext(file, lastIndex)
+        }`,
+      );
+    }
+
+    const name = scenarioRegexResult[1].trim();
+    const text = scenarioRegexResult[2].trim();
+    let rawExpected = scenarioRegexResult[3];
+
+    let expected = "";
+    let expectedErrors = "";
+    let expectedWarnings = "";
+
+    if (rawExpected.includes("errors:")) {
+      let expectedSplit = rawExpected.split(/errors:/);
+
+      expected = expectedSplit[0].trim();
+      rawExpected = expectedSplit[1] ?? "";
+
+      if (rawExpected.includes("warnings:")) {
+        expectedSplit = rawExpected.split(/warnings:/);
+        expectedErrors = (expectedSplit[0] ?? "").trim();
+        expectedWarnings = (expectedSplit[1] ?? "").trim();
+      } else {
+        expectedErrors = rawExpected.trim();
+      }
+    } else if (rawExpected.includes("warnings")) {
+      const expectedSplit = rawExpected.split(/warnings:/);
+
+      expected = expectedSplit[0].trim();
+      expectedWarnings = (expectedSplit[1] ?? "").trim();
+    } else {
+      expected = rawExpected.trim();
+    }
+
+    testScenarios.push({
+      name,
+      text,
+      expected,
+      expectedErrors,
+      expectedWarnings,
+    });
+
+    lastIndex = scenarioRegexResult.index + scenarioRegexResult[0].length;
+
+    if (lastIndex == file.length) {
+      break;
+    }
+  }
+
+  return testScenarios;
+}

package/tests/analyser/sdl-analyser-scenarios.test.ts

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, test } from "bun:test";
+import { createStrictSdlParser } from "../../src/lezer/create-sdl-parser.ts";
+import { getSdlAnalyserTestScenarios } from "./get-sdl-analyser-test-scenarios.ts";
+import { createLenientSdlAnalyser } from "../../src/analyser/create-sdl-analyser.ts";
+import { buildAst } from "../../src/ast/build-ast.ts";
+import { SdlStringInput } from "../../src/lezer/sdl-string-input.ts";
+import { getSymbolTableString } from "../../src/analyser/util/symbol-table-utils.ts";
+import type { Specification } from "../../src/ast/node/specification.ts";
+
+const sdlParser = createStrictSdlParser();
+const sdlAnalyser = createLenientSdlAnalyser(undefined);
+const testCaseDir = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "test-cases",
+);
+
+const normalize = (s: string) => s.replace(/\r\n/g, "\n");
+
+for (const filename of fs.readdirSync(testCaseDir)) {
+  if (!/\.txt$/.test(filename)) {
+    continue;
+  }
+
+  const scenarioName = /^[^\.]*/.exec(filename)?.[0] || "??";
+
+  describe(`SDL Analyser ${scenarioName} Tests`, () => {
+    const testCases = fs.readFileSync(path.join(testCaseDir, filename), "utf8");
+
+    for (
+      const testScenario of getSdlAnalyserTestScenarios(testCases, filename)
+    ) {
+      test(`Test SDL Analyser ${scenarioName} - ${testScenario.name}`, () => {
+        const sdlString = testScenario.text.trim();
+        const expectedOutput = normalize(testScenario.expected.trim());
+
+        const sdlStringInput = new SdlStringInput(sdlString);
+        const parseTree = sdlParser.parse(sdlStringInput);
+        const specification = buildAst(parseTree, sdlStringInput);
+        const actualAnalysisResult = sdlAnalyser.analyse(
+          specification as Specification,
+        );
+        const actualOutput = normalize(getSymbolTableString(
+          actualAnalysisResult.symbolTable,
+        ));
+
+        expect(actualOutput).toBe(expectedOutput);
+
+        const actualErrors = actualAnalysisResult.semanticErrors
+          .map((e) => e.errorMessage)
+          .join("\n");
+        const expectedErrors = normalize(testScenario.expectedErrors);
+
+        expect(actualErrors).toBe(expectedErrors);
+
+        const actualWarnings = actualAnalysisResult.semanticWarnings
+          .map((e) => e.errorMessage)
+          .join("\n");
+        const expectedWarnings = normalize(testScenario.expectedWarnings);
+
+        expect(actualWarnings).toBe(expectedWarnings);
+      });
+    }
+  });
+}

package/tests/analyser/semantic-error-scenarios.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test";
+
+import { Specification } from "../../src/ast/node/specification.ts";
+import { createStrictSdlAnalyser } from "../../src/analyser/create-sdl-analyser.ts";
+import { createStrictSdlParser } from "../../src/lezer/create-sdl-parser.ts";
+import { SdlStringInput } from "../../src/lezer/sdl-string-input.ts";
+import { buildAst } from "../../src/ast/build-ast.ts";
+
+const sdlParser = createStrictSdlParser();
+const sdlAnalyser = createStrictSdlAnalyser();
+
+describe("Semantic Error Scenario Tests", () => {
+  test("Empty specification ok", () => {
+    const specification = new Specification([]);
+
+    sdlAnalyser.analyse(specification);
+  });
+
+  test("Duplicate global symbol", () => {
+    const sdlStringInput = new SdlStringInput(
+      "computed int a = 1; computed int a = 2;",
+    );
+    const parseTree = sdlParser.parse(sdlStringInput);
+    const specification = buildAst(parseTree, sdlStringInput);
+
+    expect(() => sdlAnalyser.analyse(specification as Specification)).toThrow(
+      "SEMANTIC ERROR: Variable: a is already declared in scope: GLOBAL => { row: 1, column: 34, position: 33 }",
+    );
+  });
+
+  test("Undefined symbol", () => {
+    const sdlStringInput = new SdlStringInput("class A { B b;}");
+    const parseTree = sdlParser.parse(sdlStringInput);
+    const specification = buildAst(parseTree, sdlStringInput);
+
+    expect(() => sdlAnalyser.analyse(specification as Specification)).toThrow(
+      "SEMANTIC ERROR: Class: B is not declared => { row: 1, column: 11, position: 10 }",
+    );
+  });
+});

package/tests/analyser/symbol-table.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AddSymbolResult,
+  NumericType,
+  ScopeKind,
+  type Symbol,
+  SymbolKind,
+  SymbolTable,
+} from "../../src/analyser/symbol-table.ts";
+import { TokenKind } from "../../src/ast/node/enum/token-kind.ts";
+import { Token } from "../../src/ast/node/token.ts";
+import { Identifier } from "../../src/ast/node/identifier.ts";
+
+describe("Symbol Table Tests", () => {
+  const node = new Identifier(
+    "foo",
+    new Token(TokenKind.IDENTIFIER, "foo", { row: 1, column: 1, position: 0 }),
+  );
+
+  test("Test symbol table creation", () => {
+    const table = new SymbolTable();
+
+    expect(table.getCurrentScope().kind).toBe(ScopeKind.GLOBAL);
+  });
+
+  test("Define and lookup symbol in global scope", () => {
+    const table = new SymbolTable();
+    const symbol: Symbol = {
+      node,
+      name: "MyVariable",
+      kind: SymbolKind.VARIABLE,
+      attributes: {
+        isComputed: true,
+        isConst: true,
+      },
+      location: { row: 1, column: 1, position: 0 },
+    };
+
+    expect(table.addSymbol(symbol)).toBe(AddSymbolResult.SUCCESS);
+    expect(table.lookupVariable("MyVariable")).toBe(symbol);
+  });
+
+  test("Prevent duplicate symbol definition", () => {
+    const table = new SymbolTable();
+    const symbol1: Symbol = {
+      node,
+      name: "MyVariable",
+      kind: SymbolKind.VARIABLE,
+      attributes: {
+        isComputed: true,
+        isConst: true,
+      },
+      location: { row: 1, column: 1, position: 0 },
+    };
+    const symbol2: Symbol = {
+      node,
+      name: "MyVariable",
+      kind: SymbolKind.VARIABLE,
+      attributes: {
+        isComputed: true,
+        isConst: true,
+      },
+      location: { row: 1, column: 1, position: 0 },
+    };
+
+    expect(table.addSymbol(symbol1)).toBe(AddSymbolResult.SUCCESS);
+    expect(table.addSymbol(symbol2)).toBe(AddSymbolResult.DUPLICATE);
+    expect(table.lookupVariable("MyVariable")).toBe(symbol1);
+  });
+
+  test("Prevent conflicting member definition", () => {
+    const table = new SymbolTable();
+
+    const symbol1: Symbol = {
+      node,
+      name: "MyVariable",
+      kind: SymbolKind.VARIABLE,
+      attributes: {
+        numericType: NumericType.INTEGER,
+        isConst: true,
+      },
+      location: { row: 1, column: 1, position: 0 },
+    };
+    const symbol2: Symbol = {
+      node,
+      name: "MyVariable",
+      kind: SymbolKind.VARIABLE,
+      attributes: {
+        numericType: NumericType.FLOATING_POINT,
+        isConst: true,
+      },
+      location: { row: 1, column: 1, position: 0 },
+    };
+
+    table.enterClassScope("A");
+    table.enterBlockScope("COMPOUND");
+    expect(table.addSymbol(symbol1)).toBe(AddSymbolResult.SUCCESS);
+    table.exitScope();
+    table.enterBlockScope("COMPOUND");
+    expect(table.addSymbol(symbol2)).toBe(AddSymbolResult.MEMBER_CONFLICT);
+    table.exitScope();
+  });
+
+  test("Enter and exit scope", () => {
+    const table = new SymbolTable();
+
+    table.enterBlockScope("inner");
+
+    expect(table.getCurrentScope().kind).toBe(ScopeKind.BLOCK);
+    expect(table.getCurrentScope().name).toBe("inner");
+
+    table.exitScope();
+
+    expect(table.getCurrentScope().kind).toBe(ScopeKind.GLOBAL);
+  });
+
+  test("Lookup traverses parent scopes", () => {
+    const table = new SymbolTable();
+    const globalSymbol: Symbol = {
+      node,
+      name: "globalVar",
+      kind: SymbolKind.VARIABLE,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    };
+
+    table.addSymbol(globalSymbol);
+
+    table.enterBlockScope("inner");
+
+    const innerSymbol: Symbol = {
+      node,
+      name: "innerVar",
+      kind: SymbolKind.VARIABLE,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    };
+
+    table.addSymbol(innerSymbol);
+
+    expect(table.lookupVariable("globalVar")).toBe(globalSymbol);
+    expect(table.lookupVariable("innerVar")).toBe(innerSymbol);
+  });
+
+  test("lookupClass returns only CLASS symbols", () => {
+    const table = new SymbolTable();
+
+    table.addSymbol({
+      node,
+      name: "MyClass",
+      kind: SymbolKind.CLASS,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    });
+    table.addSymbol({
+      node,
+      name: "MyMap",
+      kind: SymbolKind.MAP,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    });
+
+    expect(table.lookupClass("MyClass")).toBeDefined();
+    expect(table.lookupClass("MyMap")).toBeUndefined();
+  });
+
+  test("lookupMap returns only MAP symbols", () => {
+    const table = new SymbolTable();
+
+    table.addSymbol({
+      node,
+      name: "MyClass",
+      kind: SymbolKind.CLASS,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    });
+    table.addSymbol({
+      node,
+      name: "MyMap",
+      kind: SymbolKind.MAP,
+      attributes: {},
+      location: { row: 1, column: 1, position: 0 },
+    });
+
+    expect(table.lookupMap("MyMap")).toBeDefined();
+    expect(table.lookupMap("MyClass")).toBeUndefined();
+  });
+});