@guardian-network/policy-dsl 0.3.2

package/src/antlr/index.ts

@@ -0,0 +1,3 @@
+export * from './generated/grammar/LacLangLexer';
+export * from './generated/grammar/LacLangListener';
+export * from './generated/grammar/LacLangParser';

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './antlr';
+export { nodeIdFromDeclaration } from './ir-generation';
+export { Transpiler } from './transpiler';

package/src/ir-generation/hashing.helper.ts

@@ -0,0 +1,13 @@
+import { InstanceConfig, NodeId } from '@guardian-network/shared';
+import { IRTransformer } from '.';
+
+export const nodeIdFromDeclaration = (
+  def: InstanceConfig,
+  salt: number,
+): string => {
+  const artifactIntermediateForm =
+    IRTransformer.buildIRFromInstanceDeclaration(def);
+
+  const nodeId = NodeId.fromNotation(artifactIntermediateForm, salt);
+  return nodeId;
+};

package/src/ir-generation/index.ts

@@ -0,0 +1,2 @@
+export * from './hashing.helper';
+export * from './parsed-state-to-ir.transformer';

package/src/ir-generation/parsed-state-to-ir.transformer.ts

@@ -0,0 +1,50 @@
+import {
+  InstanceConfig,
+  mapToArray,
+  TypedValue,
+} from '@guardian-network/shared';
+import { LatentState } from '../transpiler/state/LatentState';
+
+export class IRTransformer {
+  public static buildIRFromInstanceDeclaration(config: InstanceConfig): string {
+    return formatDeclaration(config);
+  }
+
+  public static buildFullIR(state: LatentState): {
+    rootNode: string;
+    definitions: string[];
+    typings: InstanceConfig[];
+  } {
+    const sortedInstances = mapToArray(state.instancesByName).sort(
+      (a, b) => a.index - b.index,
+    );
+
+    return {
+      definitions: sortedInstances.map((el) =>
+        this.buildIRFromInstanceDeclaration(el.config),
+      ),
+      rootNode: state.evaluateRelativeTo!.nodeId,
+      typings: sortedInstances.map((el) => el.config),
+    };
+  }
+}
+
+const formatArtifactClause = (artifactAddress: string) =>
+  `{${artifactAddress}}`;
+
+const formatExecArgumentsClause = (args: TypedValue[]) =>
+  `(${args.map((el) => el.value).join(',')})`;
+
+const formatInitArgumentsClause = (args: TypedValue[]) =>
+  `<${args.map((el) => el.value).join(',')}>`;
+
+const formatDeclaration = (config: InstanceConfig) => {
+  const { artifactAddress, initArguments, execArguments, needsInitialization } =
+    config;
+  const initializationClause = needsInitialization
+    ? formatInitArgumentsClause(initArguments)
+    : '';
+
+  const formatted = `${formatArtifactClause(artifactAddress)} ${formatExecArgumentsClause(execArguments)} ${initializationClause}`;
+  return formatted;
+};

package/src/transpiler/Transpiler.ts

@@ -0,0 +1,58 @@
+import { TranspilerOutput } from '@guardian-network/shared';
+import { CharStreams, CodePointCharStream, CommonTokenStream } from 'antlr4ts';
+import { ParseTreeListener } from 'antlr4ts/tree/ParseTreeListener';
+import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';
+import { LacLangLexer, LacLangParser, ProgramContext } from '../antlr';
+import { IRTransformer } from '../ir-generation';
+import { TranspilerConfig } from './helpers';
+import { LacLangTranspiler } from './listener';
+import { LatentState } from './state';
+
+export class Transpiler {
+  protected tree: ProgramContext;
+  protected listener: LacLangTranspiler;
+  protected walker: ParseTreeWalker;
+
+  // are those needed within state???
+  /* protected inputStream: CodePointCharStream;
+  protected lexer: LacLangLexer;
+  protected tokenStream: CommonTokenStream;
+  protected parser: LacLangParser; */
+
+  static create = (sources: string, options: TranspilerConfig) => {
+    return new Transpiler(sources, options);
+  };
+
+  constructor(sources: string, options: TranspilerConfig) {
+    const inputStream: CodePointCharStream = CharStreams.fromString(sources);
+    const lexer = new LacLangLexer(inputStream);
+    const tokenStream = new CommonTokenStream(lexer);
+    const parser = new LacLangParser(tokenStream);
+
+    this.tree = parser.program();
+    this.listener = new LacLangTranspiler(options);
+    this.walker = new ParseTreeWalker();
+  }
+
+  transpile() {
+    this.walker.walk(<ParseTreeListener>this.listener, this.tree);
+    return this;
+  }
+
+  toIntermediateRepresentation(): TranspilerOutput {
+    const { definitions, rootNode, typings } = IRTransformer.buildFullIR(
+      this.listener.latentState,
+    );
+    const ir = definitions.join('\r\n');
+
+    return {
+      ir,
+      rootNode,
+      typings,
+    };
+  }
+
+  getLatentState(): LatentState {
+    return this.listener.latentState;
+  }
+}

package/src/transpiler/errors/ErrorFactory.ts

@@ -0,0 +1,130 @@
+import {
+  ArtifactAlreadyDefinedError,
+  ArtifactNotDefinedError,
+  CannotInferValueTypeError,
+  ConstantIsAlreadyDefinedError,
+  ConstantNotDefinedError,
+  CyclicReferenceDSLError,
+  EvaluateAlreadyDeclaredError,
+  EvaluateTypeNotBoolError,
+  ImportAmbiguityError,
+  ImpropperInitArgsMutabilityError,
+  InstanceAlreadyDefinedError,
+  InstanceNotDefinedError,
+  NoEvaluateStatementError,
+  NonInjectedVariablesNotAllowedError,
+  SelfReferenceDSLError,
+  UnkownDirectiveError,
+  VariableAlreadyDefinedError,
+  VariableNotDefinedError,
+} from './validation-errors';
+
+export class ErrorFactory {
+  static importAmbiguity = (
+    ...params: Parameters<typeof ImportAmbiguityError.create>
+  ) => {
+    return ImportAmbiguityError.create(...params);
+  };
+
+  static nonInjectedVariable = (
+    ...params: Parameters<typeof NonInjectedVariablesNotAllowedError.create>
+  ) => {
+    return NonInjectedVariablesNotAllowedError.create(...params);
+  };
+
+  static unknownDirective = (
+    ...params: Parameters<typeof UnkownDirectiveError.create>
+  ) => {
+    return UnkownDirectiveError.create(...params);
+  };
+
+  static constantIsAlreadyDefined = (
+    ...params: Parameters<typeof ConstantIsAlreadyDefinedError.create>
+  ) => {
+    return ConstantIsAlreadyDefinedError.create(...params);
+  };
+
+  static variableAlreadyDefined = (
+    ...params: Parameters<typeof VariableAlreadyDefinedError.create>
+  ) => {
+    return VariableAlreadyDefinedError.create(...params);
+  };
+
+  static artifactAlreadyDefined = (
+    ...params: Parameters<typeof ArtifactAlreadyDefinedError.create>
+  ) => {
+    return ArtifactAlreadyDefinedError.create(...params);
+  };
+
+  static instanceAlreadyDefined = (
+    ...params: Parameters<typeof InstanceAlreadyDefinedError.create>
+  ) => {
+    return InstanceAlreadyDefinedError.create(...params);
+  };
+
+  static evaluateAlreadyDeclared = (
+    ...params: Parameters<typeof EvaluateAlreadyDeclaredError.create>
+  ) => {
+    return EvaluateAlreadyDeclaredError.create(...params);
+  };
+
+  static artifactNotDefined = (
+    ...params: Parameters<typeof ArtifactNotDefinedError.create>
+  ) => {
+    return ArtifactNotDefinedError.create(...params);
+  };
+
+  static variableNotDefined = (
+    ...params: Parameters<typeof VariableNotDefinedError.create>
+  ) => {
+    return VariableNotDefinedError.create(...params);
+  };
+
+  static constantNotDefined = (
+    ...params: Parameters<typeof ConstantNotDefinedError.create>
+  ) => {
+    return ConstantNotDefinedError.create(...params);
+  };
+
+  static instanceNotDefined = (
+    ...params: Parameters<typeof InstanceNotDefinedError.create>
+  ) => {
+    return InstanceNotDefinedError.create(...params);
+  };
+
+  static impropperInitArgsMutabilityMode = (
+    ...params: Parameters<typeof ImpropperInitArgsMutabilityError.create>
+  ) => {
+    return ImpropperInitArgsMutabilityError.create(...params);
+  };
+
+  static evaluateTypeNotBool = (
+    ...params: Parameters<typeof EvaluateTypeNotBoolError.create>
+  ) => {
+    return EvaluateTypeNotBoolError.create(...params);
+  };
+
+  static noEvaluateStatement = (
+    ...params: Parameters<typeof NoEvaluateStatementError.create>
+  ) => {
+    return NoEvaluateStatementError.create(...params);
+  };
+
+  static cyclicReferenceDSL = (
+    ...params: Parameters<typeof CyclicReferenceDSLError.create>
+  ) => {
+    return CyclicReferenceDSLError.create(...params);
+  };
+
+  static selfReferenceDSL = (
+    ...params: Parameters<typeof SelfReferenceDSLError.create>
+  ) => {
+    return SelfReferenceDSLError.create(...params);
+  };
+
+  static cannotInferValueType = (
+    ...params: Parameters<typeof CannotInferValueTypeError.create>
+  ) => {
+    return CannotInferValueTypeError.create(...params);
+  };
+}

package/src/transpiler/errors/helpers.ts

@@ -0,0 +1,4 @@
+import { ParserRuleContext } from 'antlr4ts';
+
+export const formatTranspileErrorLocation = (ctx: ParserRuleContext) =>
+  `${ctx.start.line}:${ctx.start.charPositionInLine}-${ctx.stop?.line}:${ctx.stop?.charPositionInLine}`;

package/src/transpiler/errors/index.ts

@@ -0,0 +1 @@
+export * from './ErrorFactory';

package/src/transpiler/errors/validation-errors.ts

@@ -0,0 +1,157 @@
+import { BaseError } from '@guardian-network/shared';
+import { ParserRuleContext } from 'antlr4ts';
+import { formatTranspileErrorLocation as formatLocation } from './helpers';
+
+export class ConstantIsAlreadyDefinedError extends BaseError {
+  static create = (
+    name: string,
+    selfContext: ParserRuleContext,
+    collisionContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Constant ${name} declared on ${formatLocation(selfContext)} was already defined on ${formatLocation(collisionContext)}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class VariableAlreadyDefinedError extends BaseError {
+  static create = (
+    name: string,
+    selfContext: ParserRuleContext,
+    collisionContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Variable ${name} declared on ${formatLocation(selfContext)} was already defined on ${formatLocation(collisionContext)}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class ArtifactAlreadyDefinedError extends BaseError {
+  static create = (
+    name: string,
+    selfContext: ParserRuleContext,
+    collisionContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Artifact ${name} declared on ${formatLocation(selfContext)} was already defined on ${formatLocation(collisionContext)}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class InstanceAlreadyDefinedError extends BaseError {
+  static create = (
+    name: string,
+    selfContext: ParserRuleContext,
+    collisionContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Instance ${name} declared on ${formatLocation(selfContext)} was already defined on ${formatLocation(collisionContext)}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class EvaluateAlreadyDeclaredError extends BaseError {
+  static create = (
+    selfContext: ParserRuleContext,
+    collisionContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Evaluate statement can only be declared once, but was declared on ${formatLocation(selfContext)} being already defined on ${formatLocation(collisionContext)}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class ArtifactNotDefinedError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Artifact ${name} (referenced ${formatLocation(selfContext)}) was not found in the scope`;
+    return this.build(errorMessage);
+  };
+}
+
+export class VariableNotDefinedError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Variable ${name} (referenced ${formatLocation(selfContext)}) was not found in the scope`;
+    return this.build(errorMessage);
+  };
+}
+
+export class ConstantNotDefinedError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Constant ${name} (referenced ${formatLocation(selfContext)}) was not found in the scope`;
+    return this.build(errorMessage);
+  };
+}
+
+export class InstanceNotDefinedError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Instance ${name} (referenced ${formatLocation(selfContext)}) was not found in the scope`;
+    return this.build(errorMessage);
+  };
+}
+
+export class ImpropperInitArgsMutabilityError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Variable ${name} (referenced ${formatLocation(selfContext)}) must be constant to be an initialization argument`;
+    return this.build(errorMessage);
+  };
+}
+
+export class EvaluateTypeNotBoolError extends BaseError {
+  static create = (
+    name: string,
+    selfContext: ParserRuleContext,
+    referenceContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Type of ${name} instance return value (defined ${formatLocation(referenceContext)}) (referenced ${formatLocation(selfContext)}) must be boolean to be used as a root`;
+    return this.build(errorMessage);
+  };
+}
+
+export class UnkownDirectiveError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Unknown directive ${name} (dispatched ${formatLocation(selfContext)})`;
+    return this.build(errorMessage);
+  };
+}
+
+export class ImportAmbiguityError extends BaseError {
+  static create = (troublePropertyName: string, message: string) => {
+    const errorMessage = `Importing ${troublePropertyName} error: ${message}`;
+    return this.build(errorMessage);
+  };
+}
+
+export class NonInjectedVariablesNotAllowedError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Variable ${name} (declared ${formatLocation(selfContext)}) must be "injected" because of corresponding directive`;
+    return this.build(errorMessage);
+  };
+}
+
+export class NoEvaluateStatementError extends BaseError {
+  static create = () => {
+    const errorMessage = `The program must include evaluate statement to define graph root node`;
+    return this.build(errorMessage);
+  };
+}
+
+export class CyclicReferenceDSLError extends BaseError {
+  static create = (
+    selfName: string,
+    referenceName: string,
+    selfContext: ParserRuleContext,
+    referenceContext: ParserRuleContext,
+  ) => {
+    const errorMessage = `Instance ${selfName} (defined ${formatLocation(selfContext)}) is referenced in instance ${referenceName} (defined ${formatLocation(referenceContext)}) in a cyclic manner`;
+    return this.build(errorMessage);
+  };
+}
+
+export class SelfReferenceDSLError extends BaseError {
+  static create = (name: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Instance ${name} (defined ${formatLocation(selfContext)}) is referenced in its own arguments`;
+    return this.build(errorMessage);
+  };
+}
+
+export class CannotInferValueTypeError extends BaseError {
+  static create = (value: string, selfContext: ParserRuleContext) => {
+    const errorMessage = `Can not infer type of a literal value ${value} (encountered ${formatLocation(selfContext)})`;
+    return this.build(errorMessage);
+  };
+}

package/src/transpiler/helpers/formatter.ts

@@ -0,0 +1,173 @@
+import { InstanceConfig, TypedValue } from '@guardian-network/shared';
+import { InstanceDeclarationContext, LiteralContext } from '../../antlr';
+import { ErrorFactory } from '../errors/ErrorFactory';
+import { LatentState } from '../state/LatentState';
+import { Artifacts } from '../state/types';
+import { lookupOrThrow } from './validations.helper';
+
+export const extractAndLookupExecArguments = (
+  ctx: InstanceDeclarationContext,
+  latentState: LatentState,
+): TypedValue[] => {
+  if (!ctx.argumentsList()) return [];
+
+  return ctx
+    .argumentsList()!
+    .identifier_or_literal()
+    .map((el) => {
+      if (el.literal()) {
+        return inferTypedValue(el.literal()!);
+      }
+
+      const name = el.text;
+      const refConst = latentState.constants.get(name);
+
+      if (!refConst) {
+        const refVar = latentState.variables.get(name);
+        if (!refVar) {
+          const refInst = lookupOrThrow(
+            name,
+            latentState.instancesByName,
+            ErrorFactory.variableNotDefined(name, el.ruleContext),
+          );
+
+          return {
+            value: formatInstanceReference(refInst.id),
+            type: refInst.type,
+            substitution: true,
+          };
+        } else
+          return {
+            value: 'var' + name + `$${refVar.injection}`,
+            type: refVar.type,
+          };
+      } else {
+        if (refConst.type == 'bytes') {
+          return {
+            value: formatBytesLiteral(refConst.value),
+            type: refConst.type,
+            constant: true,
+          };
+        } else
+          return {
+            value: refConst.value,
+            type: refConst.type,
+            constant: true,
+          };
+      }
+    });
+};
+
+export const extractAndLookupInitArguments = (
+  ctx: InstanceDeclarationContext,
+  latentState: LatentState,
+): TypedValue[] | null => {
+  if (!ctx.WITH_KEYWORD()) return null;
+  if (!ctx.constantsList()) return [];
+
+  return ctx
+    .constantsList()!
+    .argumentsList()
+    .identifier_or_literal()
+    .map((el) => {
+      if (!!el.literal()) {
+        return inferTypedValue(el.literal()!);
+      }
+
+      const name = el.text;
+      const refConst = latentState.constants.get(name);
+
+      if (refConst) {
+        if (refConst.type == 'bytes') {
+          return {
+            value: formatBytesLiteral(refConst.value),
+            type: refConst.type,
+          };
+        } else
+          return {
+            value: refConst.value,
+            type: refConst.type,
+          };
+      } else {
+        lookupOrThrow(
+          name,
+          latentState.variables,
+          ErrorFactory.constantNotDefined(name, el.ruleContext),
+        );
+
+        throw ErrorFactory.impropperInitArgsMutabilityMode(
+          name,
+          el.ruleContext,
+        );
+      }
+    });
+};
+
+export const extractReferenceNodeIds = (config: InstanceConfig) => {
+  const substitutions = config.execArguments.filter((arg) => arg.substitution);
+
+  const referencesNodeIdList = substitutions.map(({ value }) =>
+    value.replaceAll('|', ''),
+  );
+  return referencesNodeIdList;
+};
+
+export const dereferenceArtifact = (
+  ctx: InstanceDeclarationContext,
+  artifactsMap: Artifacts,
+) => {
+  if (ctx.identifier_or_literal().literal()) {
+    const artifactDereferenced = ctx.identifier_or_literal().literal()!.text;
+    return artifactDereferenced;
+  }
+
+  const artifactName = ctx.identifier_or_literal().IDENTIFIER()!.text;
+  const { address } = lookupOrThrow(
+    artifactName,
+    artifactsMap,
+    ErrorFactory.artifactNotDefined(artifactName, ctx),
+  );
+
+  const artifactDereferenced = address;
+  return artifactDereferenced;
+};
+
+const inferTypedValue = (ctx: LiteralContext): TypedValue => {
+  let type: string;
+  let value = ctx.text;
+
+  switch (true) {
+    case !!ctx.ADDRESS_LITERAL():
+      type = 'address';
+      break;
+    case !!ctx.BOOL_LITERAL():
+      type = 'bool';
+      break;
+    case !!ctx.STRING_LITERAL():
+      type = 'string';
+      break;
+    case !!ctx.BYTES_LITERAL():
+      type = 'bytes';
+      value = formatBytesLiteral(value);
+      break;
+    case !!ctx.NUMBER_LITERAL():
+      type = 'number';
+      break;
+    default:
+      throw ErrorFactory.cannotInferValueType(ctx.text, ctx);
+  }
+
+  return {
+    type,
+    value,
+    constant: true,
+  };
+};
+
+const formatBytesLiteral = (value: string) => {
+  return value.replace(/^'|'$/g, '');
+};
+
+export const formatInstanceReference = (nodeId: string) => {
+  return `|${nodeId}|`;
+};

package/src/transpiler/helpers/index.ts

@@ -0,0 +1,4 @@
+export * from './formatter';
+export * from './resources.helper';
+export * from './types';
+export * from './validations.helper';

package/src/transpiler/helpers/resources.helper.ts

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import fetchSycn from 'sync-fetch';
+
+const DEFAULT_ENCODING = 'utf-8';
+
+export const isLocalUrl = (url: string) =>
+  /^([a-zA-Z]:)?(\\|\/)([^\\\/]+(\\|\/)?)+$/.test(url);
+export const isLocalRelativeUrl = (url: string) =>
+  /^(\.\.\/|\.\/)?([^\\\/]+(\\|\/)?)+$/.test(url);
+
+const isHttpsUrl = (url: string) => /^https?:\/\//.test(url);
+const isSshUrl = (url: string) => /^git@[^:]+:[^/]+\/.+\.git$/.test(url);
+
+/*
+The note about sync
+
+The listener approach of the chosen Antlr transpiler is working sequentially:
+1. The parse tree is traversed (```.walk```)
+2. The listener hooks invoked on each node of the parse tree
+
+The hooks (e.g. 'enterImportStatement') are void-returning by the nature. So, the hooks are synchronous.
+That is the problem, the next traversing step won't wait 'till previous is resolved 'cause it's void anyways.
+And an asynchronous logic in hooks can not be applied before the next step possibly needing it.
+
+There is 3 solutions:
+1. Using Visitor approach and evaluate every parsing tree node by hand
+2. Rewrite the antlr core so the "walk" awaits
+3. Use only sync functions in hooks
+
+The third is most appropriate by now, hence not the most elegant.
+To synchronize the http request, one may want:
+1. Create a worker with all the asynchronous logic
+2. Execute this worker in a synchronus manner inside the main thread
+
+All the above is encapsulated in "sync-fetch" using 'execSync' of 'node:process'.
+Not the best solution, but for sync fetching of remote imports - it's OK.
+*/
+
+export const fetchContent = (url: string): string => {
+  let content: string;
+
+  switch (true) {
+    case isSshUrl(url):
+      throw new Error('Not implemented import resource type: SSH');
+
+    case isHttpsUrl(url):
+      content = readFromHttp(url);
+      break;
+
+    case isLocalUrl(url):
+    case isLocalRelativeUrl(url):
+      content = readFromFile(url);
+      break;
+
+    default:
+      throw new Error(`Not supported import resource type: ${url}`);
+  }
+
+  return content;
+};
+
+const readFromFile = (filePath: string): string => {
+  try {
+    const content = readFileSync(filePath, DEFAULT_ENCODING);
+    return content;
+  } catch (error: any) {
+    throw new Error(
+      `Error reading file at ${filePath} with description ${error.message}`,
+    );
+  }
+};
+
+const readFromHttp = (url: string): string => {
+  const response = fetchSycn(url);
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch file from remote URL: ${url}, status: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  return response.text();
+};