@guardian-network/policy-dsl 0.3.2

package/src/transpiler/helpers/types.ts

@@ -0,0 +1,23 @@
+import {
+  InstanceConfigArgumentsOnly,
+  NodeTreeInitData as ParsingResult,
+} from '@guardian-network/shared';
+
+export type InnerValidationMiddleware = (
+  artifactAddress: string,
+  currentInstanceConfig: InstanceConfigArgumentsOnly,
+) => Promise<void>;
+
+export type OuterValidationMiddlerware = (
+  output: ParsingResult[],
+) => Promise<void>;
+
+export type ValidationMiddlware = {
+  innerValidations: InnerValidationMiddleware;
+  outerValidations: OuterValidationMiddlerware;
+};
+
+export type TranspilerConfig = {
+  partialSources?: boolean;
+  sourcesDir: string;
+};

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

@@ -0,0 +1,69 @@
+import { findCycle, mapToArray, TypedValue } from '@guardian-network/shared';
+import { ParserRuleContext } from 'antlr4ts';
+import { ErrorFactory } from '../errors/ErrorFactory';
+import { extractReferenceNodeIds, formatInstanceReference } from '../helpers';
+import { InstancesById, InstancesByName } from '../state/types';
+
+export const lookupOrThrow = <T>(
+  key: string,
+  storage: Map<string, T>,
+  error: Error,
+) => {
+  const item = storage.get(key);
+
+  if (!item) throw error;
+
+  return item;
+};
+
+export const lookupAndThrow = <T>(
+  key: string,
+  storage: Map<string, T>,
+  errorMorph: (item: T) => Error,
+) => {
+  const item = storage.get(key);
+
+  if (!!item) throw errorMorph(item);
+};
+
+export const findCycleAndThrow = (
+  instancesByNameMap: InstancesByName,
+  instancesByIdMap: InstancesById,
+) => {
+  const instancesList = mapToArray(instancesByNameMap);
+
+  const nodesList = instancesList.map((instance) => ({
+    id: instance.id,
+    references: extractReferenceNodeIds(instance.config),
+  }));
+
+  const cycleFound = findCycle(nodesList);
+
+  if (!!cycleFound) {
+    const invokingNode = instancesByIdMap.get(cycleFound.parentNodeId)!;
+    const referencedNode = instancesByIdMap.get(cycleFound.nodeId)!;
+
+    throw ErrorFactory.cyclicReferenceDSL(
+      invokingNode.name,
+      referencedNode.name,
+      invokingNode.ctx,
+      referencedNode.ctx,
+    );
+  }
+};
+
+export const findSelfReferenceAndThrow = (
+  instanceName: string,
+  instanceId: string, // same as nodeId
+  execArguments: TypedValue[],
+  ctx: ParserRuleContext,
+) => {
+  const maybeSelfReference = execArguments.find(
+    ({ substitution, value }) =>
+      !!substitution && value == formatInstanceReference(instanceId),
+  );
+
+  if (!!maybeSelfReference) {
+    throw ErrorFactory.selfReferenceDSL(instanceName, ctx);
+  }
+};

package/src/transpiler/index.ts

@@ -0,0 +1,2 @@
+export * from './helpers';
+export { Transpiler } from './Transpiler';

package/src/transpiler/listener.ts

@@ -0,0 +1,180 @@
+import { InstanceConfig } from '@guardian-network/shared';
+import { join, normalize } from 'node:path';
+import {
+  ArtifactDeclarationContext,
+  ConstantDeclarationContext,
+  DirectiveContext,
+  EvaluateStatementContext,
+  ImportStatementContext,
+  InstanceDeclarationContext,
+  LacLangListener,
+  ProgramContext,
+  VarDeclarationContext,
+} from '../antlr';
+import { nodeIdFromDeclaration as calculateNodeId } from '../ir-generation';
+import { ErrorFactory } from './errors/ErrorFactory';
+import {
+  dereferenceArtifact,
+  extractAndLookupExecArguments,
+  extractAndLookupInitArguments,
+  fetchContent,
+  isLocalRelativeUrl,
+  isLocalUrl,
+  TranspilerConfig,
+} from './helpers';
+import {
+  findCycleAndThrow,
+  findSelfReferenceAndThrow,
+  lookupAndThrow,
+  lookupOrThrow,
+} from './helpers/validations.helper';
+import { LatentState } from './state/LatentState';
+import { Transpiler } from './Transpiler';
+
+export class LacLangTranspiler implements LacLangListener {
+  public latentState: LatentState = new LatentState();
+  private config: TranspilerConfig;
+
+  constructor(options: TranspilerConfig) {
+    this.config = options;
+  }
+
+  enterDirective(ctx: DirectiveContext) {
+    switch (true) {
+      case !!ctx.directiveIndentifier().injectedOnlyDirective():
+        this.latentState.setInjectionConstraint(false);
+        break;
+      default:
+        throw ErrorFactory.unknownDirective(
+          ctx.directiveIndentifier().text,
+          ctx,
+        );
+    }
+  }
+
+  enterImportStatement(ctx: ImportStatementContext) {
+    const url = ctx.STRING_LITERAL().text.replace(/^['"]|['"]$/g, '');
+    const normalizedUrl =
+      isLocalUrl(url) || isLocalRelativeUrl(url)
+        ? normalize(join(this.config.sourcesDir, url))
+        : url;
+
+    const sources = fetchContent(normalizedUrl);
+
+    const subTranspiler = Transpiler.create(sources, {
+      partialSources: true,
+      sourcesDir: this.config.sourcesDir,
+    });
+    subTranspiler.transpile();
+
+    const subState = subTranspiler.getLatentState();
+    this.latentState.merge(subState);
+  }
+
+  enterVarDeclaration(ctx: VarDeclarationContext): void {
+    const name = ctx.IDENTIFIER().text;
+
+    lookupAndThrow(name, this.latentState.variables, (declared) =>
+      ErrorFactory.variableAlreadyDefined(name, ctx, declared.ctx),
+    );
+
+    this.latentState.setVariables(ctx);
+  }
+
+  enterConstantDeclaration(ctx: ConstantDeclarationContext) {
+    const name = ctx.IDENTIFIER().text;
+
+    lookupAndThrow(name, this.latentState.constants, (declared) =>
+      ErrorFactory.constantIsAlreadyDefined(name, ctx, declared.ctx),
+    );
+
+    this.latentState.setConstants(ctx);
+  }
+
+  enterArtifactDeclaration(ctx: ArtifactDeclarationContext) {
+    const name = ctx.IDENTIFIER().text;
+
+    lookupAndThrow(name, this.latentState.artifacts, (declared) =>
+      ErrorFactory.artifactAlreadyDefined(name, ctx, declared.ctx),
+    );
+
+    this.latentState.setArtifacts(ctx);
+  }
+
+  enterInstanceDeclaration(ctx: InstanceDeclarationContext) {
+    const name = ctx.IDENTIFIER().text;
+
+    lookupAndThrow(name, this.latentState.instancesByName, (declared) =>
+      ErrorFactory.instanceAlreadyDefined(name, ctx, declared.ctx),
+    );
+
+    const execArguments = extractAndLookupExecArguments(ctx, this.latentState);
+    const initArguments = extractAndLookupInitArguments(ctx, this.latentState);
+
+    const artifactDereferenced = dereferenceArtifact(
+      ctx,
+      this.latentState.artifacts,
+    );
+
+    const instanceConfig: InstanceConfig = {
+      artifactAddress: artifactDereferenced,
+      needsInitialization: !!initArguments,
+      execArguments,
+      initArguments: initArguments ?? [],
+    };
+
+    const instancesCount = this.latentState.instancesByName.size;
+    const nodeId = calculateNodeId(instanceConfig, instancesCount);
+
+    // note: may be redundant cause in this case instance will not be even defined yet
+    findSelfReferenceAndThrow(name, nodeId, execArguments, ctx);
+
+    this.latentState.setInstancesByName(
+      ctx,
+      nodeId,
+      instanceConfig,
+      instancesCount,
+    );
+
+    this.latentState.setInstancesById(
+      ctx,
+      nodeId,
+      instanceConfig,
+      instancesCount,
+    );
+
+    // note: may be redundant due to linear declaration by design
+    findCycleAndThrow(
+      this.latentState.instancesByName,
+      this.latentState.instancesById,
+    );
+  }
+
+  enterEvaluateStatement(ctx: EvaluateStatementContext) {
+    const previouslyDeclared = this.latentState.evaluateRelativeTo;
+    if (!!previouslyDeclared) {
+      throw ErrorFactory.evaluateAlreadyDeclared(ctx, previouslyDeclared.ctx);
+    }
+
+    const instanceName = ctx.IDENTIFIER().text;
+    const refInst = lookupOrThrow(
+      instanceName,
+      this.latentState.instancesByName,
+      ErrorFactory.instanceNotDefined(instanceName, ctx),
+    );
+
+    if (refInst.type != 'bool')
+      throw ErrorFactory.evaluateTypeNotBool(instanceName, ctx, refInst.ctx);
+
+    this.latentState.setEvaluateRelativeTo = {
+      nodeId: refInst.id,
+      ctx,
+    };
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  exitProgram(_: ProgramContext) {
+    if (!this.latentState.evaluateRelativeTo && !this.config.partialSources)
+      throw ErrorFactory.noEvaluateStatement();
+  }
+}

package/src/transpiler/state/LatentState.ts

@@ -0,0 +1,202 @@
+import { InstanceConfig } from '@guardian-network/shared';
+import {
+  ArtifactDeclarationContext,
+  ConstantDeclarationContext,
+  InstanceDeclarationContext,
+  VarDeclarationContext,
+} from '../../antlr';
+import { ErrorFactory } from '../errors';
+import {
+  Artifacts,
+  Constants,
+  Evaluating,
+  InstancesById,
+  InstancesByName,
+  Variables,
+} from './types';
+
+export class LatentState {
+  private constantsMap: Constants;
+
+  private variablesMap: Variables;
+
+  private artifactsMap: Artifacts;
+
+  private instancesByNameMap: InstancesByName;
+
+  private instancesByIdMap: InstancesById;
+
+  private evaluateRelativeToInternal?: Evaluating;
+
+  private onlyInjectedVariables?: boolean;
+
+  // note: value properties (not Map) must not have defaults because :196 constraint
+  constructor() {
+    this.constantsMap = new Map();
+
+    this.variablesMap = new Map();
+
+    this.artifactsMap = new Map();
+
+    this.instancesByNameMap = new Map();
+
+    this.instancesByIdMap = new Map();
+  }
+
+  get constants() {
+    return this.constantsMap;
+  }
+
+  get variables() {
+    return this.variablesMap;
+  }
+
+  get artifacts() {
+    return this.artifactsMap;
+  }
+
+  get instancesByName() {
+    return this.instancesByNameMap;
+  }
+
+  get instancesById() {
+    return this.instancesByIdMap;
+  }
+
+  get evaluateRelativeTo() {
+    return this.evaluateRelativeToInternal;
+  }
+  set setEvaluateRelativeTo(value: Evaluating) {
+    this.evaluateRelativeToInternal = value;
+  }
+
+  setVariables(ctx: VarDeclarationContext) {
+    const { text: name } = ctx.IDENTIFIER();
+    const { text: type } = ctx.dataType();
+
+    let injection = ctx.injectionModifier()?.STRING_LITERAL().text;
+
+    if (!injection && this.onlyInjectedVariables)
+      throw ErrorFactory.nonInjectedVariable(name, ctx);
+
+    injection = injection ?? '';
+
+    this.variablesMap.set(name, { type, ctx, injection });
+  }
+
+  setConstants(ctx: ConstantDeclarationContext) {
+    const { text: name } = ctx.IDENTIFIER();
+    const { text: value } = ctx.literal();
+    const { text: type } = ctx.dataType();
+
+    this.constantsMap.set(name, {
+      value,
+      type,
+      ctx,
+    });
+  }
+
+  setArtifacts(ctx: ArtifactDeclarationContext) {
+    const { text: name } = ctx.IDENTIFIER();
+    const { text: address } = ctx.ADDRESS_LITERAL();
+
+    this.artifactsMap.set(name, {
+      address,
+      ctx,
+    });
+  }
+
+  setInstancesByName(
+    ctx: InstanceDeclarationContext,
+    nodeId: string,
+    instanceConfig: InstanceConfig,
+    instancesCount: number,
+  ) {
+    const { text: name } = ctx.IDENTIFIER();
+    const { text: type } = ctx.dataType();
+
+    this.instancesByNameMap.set(name, {
+      id: nodeId,
+      config: instanceConfig,
+      type,
+      index: instancesCount,
+      ctx,
+    });
+  }
+
+  setInstancesById(
+    ctx: InstanceDeclarationContext,
+    nodeId: string,
+    instanceConfig: InstanceConfig,
+    instancesCount: number,
+  ) {
+    const { text: name } = ctx.IDENTIFIER();
+    const { text: type } = ctx.dataType();
+
+    this.instancesByIdMap.set(nodeId, {
+      name,
+      config: instanceConfig,
+      type,
+      index: instancesCount,
+      ctx,
+    });
+  }
+
+  setInjectionConstraint(allowNonInjectedVariables: boolean) {
+    this.onlyInjectedVariables = !allowNonInjectedVariables;
+  }
+
+  merge(subState: LatentState) {
+    for (const property of Object.keys(this)) {
+      const indexingProperty = <keyof LatentState>property;
+
+      try {
+        if (this[indexingProperty] instanceof Map) {
+          this.concatMaps(
+            <Map<string, any>>subState[indexingProperty],
+            this[indexingProperty],
+          );
+        } else {
+          this.moveValue(subState[indexingProperty], this[indexingProperty]);
+        }
+      } catch (e) {
+        throw ErrorFactory.importAmbiguity(property, (<Error>e).message);
+      }
+    }
+  }
+
+  private concatMaps<T>(
+    source: Map<string, T | T[]>,
+    target: Map<string, T | T[]>,
+  ) {
+    for (const originalKey of source.keys()) {
+      const originalValue = source.get(originalKey) as T;
+
+      if (target.get(originalKey) != undefined) {
+        if (Array.isArray(originalValue)) {
+          target.set(
+            originalKey,
+            originalValue.concat(target.get(originalKey)).sort(),
+          );
+          return;
+        }
+
+        throw new Error(
+          `Ambiguity while merging maps: target already has "${originalKey}" record`,
+        );
+      }
+
+      target.set(originalKey, originalValue);
+    }
+  }
+
+  private moveValue<T>(source: T, target: T) {
+    if (!!target) {
+      throw new Error(
+        `Ambiguity while merging values: target already set to "${target}"`,
+      );
+    }
+
+    target = source;
+  }
+}

package/src/transpiler/state/index.ts

@@ -0,0 +1,2 @@
+export * from './LatentState';
+export * from './types';

package/src/transpiler/state/types.ts

@@ -0,0 +1,50 @@
+import { InstanceConfig } from '@guardian-network/shared';
+import { ParserRuleContext } from 'antlr4ts';
+
+type KeyType = string;
+type IdKeyType = KeyType;
+type NameKeyType = KeyType;
+
+type DataType = { type: string };
+type AddressType = {
+  address: string;
+};
+type NameType = {
+  name: string;
+};
+type NodeIdType = {
+  nodeId: string;
+};
+type IndexType = {
+  index: number;
+};
+type ConfigType = {
+  config: InstanceConfig;
+};
+type InjectionType = { injection: string };
+type ValueType = { value: string };
+
+type ContextWrapped = { ctx: ParserRuleContext };
+
+export type Constants = Map<KeyType, ValueType & DataType & ContextWrapped>;
+
+export type Variables = Map<KeyType, DataType & ContextWrapped & InjectionType>;
+
+export type Artifacts = Map<KeyType, AddressType & ContextWrapped>;
+
+export type InstancesByName = Map<
+  NameKeyType,
+  {
+    id: string;
+  } & IndexType &
+    ConfigType &
+    DataType &
+    ContextWrapped
+>;
+
+export type InstancesById = Map<
+  IdKeyType,
+  NameType & IndexType & ConfigType & DataType & ContextWrapped
+>;
+
+export type Evaluating = NodeIdType & ContextWrapped;