Merge pull request #913 from Green-Software-Foundation/explain-feature

Add `explain` feature

src/__tests__/if-run/lib/explain.test.ts

@@ -0,0 +1,86 @@
+import {explain, addExplainData} from '../../../if-run/lib/explain';
+
+describe('lib/explain: ', () => {
+  it('successfully adds explain data if `inputs` and `outputs` of `metadata` are `undefined`.', () => {
+    const mockData = {
+      pluginName: 'divide',
+      metadata: {kind: 'execute', inputs: undefined, outputs: undefined},
+      pluginData: {
+        path: 'builtin',
+        method: 'Divide',
+      },
+    };
+    const expectedResult = {
+      divide: {
+        method: 'Divide',
+        path: 'builtin',
+        inputs: 'undefined',
+        outputs: 'undefined',
+      },
+    };
+
+    addExplainData(mockData);
+    const result = explain();
+    expect.assertions(1);
+    expect(result).toEqual(expectedResult);
+  });
+
+  it('successfully adds explain data if `inputs` and `outputs` of `metadata` are valid data.', () => {
+    const mockData = {
+      pluginName: 'sum',
+      metadata: {
+        kind: 'execute',
+        inputs: {
+          'cpu/energy': {
+            unit: 'kWh',
+            description: 'energy consumed by the cpu',
+          },
+          'network/energy': {
+            unit: 'kWh',
+            description: 'energy consumed by data ingress and egress',
+          },
+        },
+        outputs: {
+          'energy-sum': {
+            unit: 'kWh',
+            description: 'sum of energy components',
+          },
+        },
+      },
+      pluginData: {
+        path: 'builtin',
+        method: 'Sum',
+      },
+    };
+    const expectedResult = {
+      divide: {
+        method: 'Divide',
+        path: 'builtin',
+        inputs: 'undefined',
+        outputs: 'undefined',
+      },
+      sum: {
+        method: 'Sum',
+        path: 'builtin',
+        inputs: {
+          'cpu/energy': {
+            unit: 'kWh',
+            description: 'energy consumed by the cpu',
+          },
+          'network/energy': {
+            unit: 'kWh',
+            description: 'energy consumed by data ingress and egress',
+          },
+        },
+        outputs: {
+          'energy-sum': {unit: 'kWh', description: 'sum of energy components'},
+        },
+      },
+    };
+
+    addExplainData(mockData);
+    const result = explain();
+    expect.assertions(1);
+    expect(result).toEqual(expectedResult);
+  });
+});

src/common/util/validations.ts

@@ -38,6 +38,8 @@ export const manifestSchema = z.object({
     })
     .optional()
     .nullable(),
+  explainer: z.boolean().optional(),
+  explain: z.record(z.string(), z.any()).optional(),
   aggregation: z
     .object({
       metrics: z.record(

src/if-env/util/helpers.ts

@@ -16,7 +16,7 @@ import {STRINGS} from '../config';
 
 import {EnvironmentOptions} from '../types/if-env';
 
-const {MissingPluginDependenciesError} = ERRORS;
+const {MissingManifestDependenciesError} = ERRORS;
 const {
   FAILURE_MESSAGE_DEPENDENCIES,
   FAILURE_MESSAGE,
@@ -38,7 +38,7 @@ export const getOptionsFromArgs = async (commandArgs: {
   const dependencies = rawManifest?.execution?.environment.dependencies || [];
 
   if (!dependencies.length) {
-    throw new MissingPluginDependenciesError(FAILURE_MESSAGE_DEPENDENCIES);
+    throw new MissingManifestDependenciesError(FAILURE_MESSAGE_DEPENDENCIES);
   }
 
   const pathsWithVersion = extractPathsWithVersion(plugins, dependencies);

src/if-run/index.ts

@@ -14,6 +14,7 @@ import {debugLogger} from '../common/util/debug-logger';
 
 import {STRINGS} from './config';
 import {STRINGS as COMMON_STRINGS} from '../common/config';
+import {explain} from './lib/explain';
 
 const {EXITING_IF, STARTING_IF} = STRINGS;
 const {DISCLAIMER_MESSAGE} = COMMON_STRINGS;
@@ -39,6 +40,9 @@ const impactEngine = async () => {
     const pluginStorage = await initialize(context.initialize.plugins);
     const computedTree = await compute(tree, {context, pluginStorage});
     const aggregatedTree = aggregate(computedTree, context.aggregation);
+
+    envManifest.explainer && (context.explain = explain());
+
     await exhaust(aggregatedTree, context, outputOptions);
   } catch (error) {
     if (error instanceof Error) {

src/if-run/lib/compute.ts

@@ -7,6 +7,7 @@ import {STRINGS} from '../config/strings';
 
 import {isExecute, isGroupBy} from '../types/interface';
 import {ComputeParams, Node, Params} from '../types/compute';
+import {addExplainData} from './explain';
 
 const {MERGING_DEFAULTS_WITH_INPUT_DATA, COMPUTING_PIPELINE_FOR_NODE} = STRINGS;
 
@@ -78,6 +79,15 @@ const computeNode = async (node: Node, params: Params): Promise<any> => {
 
     if (isExecute(plugin)) {
       inputStorage = await plugin.execute(inputStorage, nodeConfig);
+
+      if (params.context.explainer) {
+        addExplainData({
+          pluginName,
+          metadata: plugin.metadata,
+          pluginData: params.context.initialize.plugins[pluginName],
+        });
+      }
+
       debugLogger.setExecutingPluginName();
 
       node.outputs = inputStorage;

src/if-run/lib/explain.ts

@@ -0,0 +1,44 @@
+import {ExplainParams} from '../types/explain';
+
+/**
+ * Retrieves stored explain data.
+ */
+export const explain = () => storeExplainData.plugins;
+
+/**
+ * Manages the storage of explain data.
+ */
+const storeExplainData = (() => {
+  let plugin = {};
+
+  const pluginManager = {
+    get plugins() {
+      return plugin;
+    },
+    set plugins(value: object) {
+      plugin = value;
+    },
+  };
+
+  return pluginManager;
+})();
+
+/**
+ * Adds new explain data to the stored explain data.
+ */
+export const addExplainData = (params: ExplainParams) => {
+  const {pluginName, pluginData, metadata} = params;
+  const plugin = {
+    [pluginName]: {
+      method: pluginData.method,
+      path: pluginData.path,
+      inputs: metadata?.inputs || 'undefined',
+      outputs: metadata?.outputs || 'undefined',
+    },
+  };
+
+  storeExplainData.plugins = {
+    ...storeExplainData.plugins,
+    ...plugin,
+  };
+};

src/if-run/types/explain.ts

@@ -0,0 +1,7 @@
+import {ParameterMetadata} from '@grnsft/if-core/types';
+
+export type ExplainParams = {
+  pluginName: string;
+  pluginData: {method: string; path: string};
+  metadata: {inputs?: ParameterMetadata; outputs?: ParameterMetadata};
+};