@grnsft/if 0.4.0-beta.1 → 0.5.0-beta.0

package/manifests/plugins/divide/failure-denominator-equal-zero.yml

@@ -5,8 +5,14 @@ initialize:
 #  outputs: ['yaml']
   plugins:
     cloud-metadata:
-      method: CloudMetadata
-      path: "@grnsft/if-plugins"
+      path: builtin
+      method: CSVLookup
+      global-config:
+        filepath: >-
+          https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv
+        query:
+          instance-class: cloud/instance-type
+        output: ['cpu-cores-utilized', 'vcpus-allocated']
     divide:
       method: Divide
       path: "builtin"
@@ -14,19 +20,12 @@ initialize:
         numerator: vcpus-allocated
         denominator: 0
         output: cpu/number-cores
-    boavizta-cpu:
-      method: BoaviztaCpuOutput
-      path: "@grnsft/if-unofficial-plugins"
-      global-config:
-        allocation: LINEAR
-        verbose: true
 tree:
   children:
     child:
       pipeline:
         - cloud-metadata
         - divide
-        - boavizta-cpu
       config:
         divide:
       defaults:

package/manifests/plugins/divide/failure-invalid-config-denominator.yml

@@ -5,8 +5,14 @@ initialize:
   outputs: ['yaml']
   plugins:
     cloud-metadata:
-      method: CloudMetadata
-      path: "@grnsft/if-plugins"
+      path: builtin
+      method: CSVLookup
+      global-config:
+        filepath: >-
+          https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv
+        query:
+          instance-class: cloud/instance-type
+        output: ['cpu-cores-utilized', 'vcpus-allocated']
     divide:
       method: Divide
       path: "builtin"
@@ -14,19 +20,12 @@ initialize:
         numerator: vcpus-allocated
         denominator: 'vcpus'
         output: cpu/number-cores
-    boavizta-cpu:
-      method: BoaviztaCpuOutput
-      path: "@grnsft/if-unofficial-plugins"
-      global-config:
-        allocation: LINEAR
-        verbose: true
 tree:
   children:
     child:
       pipeline:
         - cloud-metadata
         - divide
-        - boavizta-cpu
       config:
         divide:
       defaults:

package/manifests/plugins/divide/failure-missing-numerator.yml

@@ -5,8 +5,14 @@ initialize:
 #  outputs: ['yaml']
   plugins:
     cloud-metadata:
-      method: CloudMetadata
-      path: "@grnsft/if-plugins"
+      path: builtin
+      method: CSVLookup
+      global-config:
+        filepath: >-
+          https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv
+        query:
+          instance-class: cloud/instance-type
+        output: ['cpu-cores-utilized', 'vcpus-allocated']
     divide:
       method: Divide
       path: "builtin"
@@ -14,19 +20,12 @@ initialize:
         #numerator: vcpus-allocated
         denominator: 2
         output: cpu/number-cores
-    boavizta-cpu:
-      method: BoaviztaCpuOutput
-      path: "@grnsft/if-unofficial-plugins"
-      global-config:
-        allocation: LINEAR
-        verbose: true
 tree:
   children:
     child:
       pipeline:
         - cloud-metadata
         - divide
-        - boavizta-cpu
       config:
         divide:
       defaults:

package/manifests/plugins/divide/success.yml

@@ -2,11 +2,17 @@ name: divide
 description: success path
 tags:
 initialize:
-#  outputs: ['yaml']
+  # outputs: ['yaml']
   plugins:
     cloud-metadata:
-      method: CloudMetadata
-      path: "@grnsft/if-plugins"
+      path: builtin
+      method: CSVLookup
+      global-config:
+        filepath: >-
+          https://raw.githubusercontent.com/Green-Software-Foundation/if-data/main/cloud-metdata-aws-instances.csv
+        query:
+          instance-class: cloud/instance-type
+        output: ['cpu-cores-utilized', 'vcpus-allocated']
     divide:
       method: Divide
       path: "builtin"
@@ -14,19 +20,12 @@ initialize:
         numerator: vcpus-allocated
         denominator: 2
         output: cpu/number-cores
-    boavizta-cpu:
-      method: BoaviztaCpuOutput
-      path: "@grnsft/if-unofficial-plugins"
-      global-config:
-        allocation: LINEAR
-        verbose: true
 tree:
   children:
     child:
       pipeline:
         - cloud-metadata
         - divide
-        - boavizta-cpu
       config:
         divide:
       defaults:

package/manifests/plugins/exponent/success.yml

@@ -0,0 +1,26 @@
+name: exponent demo
+description:
+tags:
+initialize:
+  # outputs:
+  #   - yaml
+  plugins:
+    exponent:
+      method: Exponent
+      path: 'builtin'
+      global-config:
+        input-parameter: 'cpu/energy'
+        exponent: 2
+        output-parameter: 'energy'
+tree:
+  children:
+    child:
+      pipeline:
+        - exponent
+      config:
+        exponent:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.001
+          network/energy: 0.001

package/manifests/plugins/interpolation/success.yml

@@ -0,0 +1,24 @@
+name: interpolation-demo
+description: simple demo of interpolation plugin
+tags:
+initialize:
+  plugins:
+    interpolation:
+      method: Interpolation
+      path: "builtin"
+      global-config:
+        method: linear
+        x: [0, 10, 50, 100]
+        y: [0.12, 0.32, 0.75, 1.02]
+        input-parameter: "cpu/utilization"
+        output-parameter: "result"
+
+tree:
+  children:
+    child:
+      pipeline:
+        - interpolation
+      inputs:
+        - timestamp: 2023-07-06T00:00
+          duration: 3600
+          cpu/utilization: 45

package/manifests/plugins/sci/failure-missing-input-param.yml

@@ -8,17 +8,13 @@ initialize:
       kind: plugin
       method: Sci
       path: "builtin"
-      # global-config:
-      #   functional-unit: requests
+      global-config:
+        functional-unit: requests
 tree:
   children:
     child:
       pipeline:
         - sci
-      config:
-        sci:
-          functional-unit-time: 1 sec
-          functional-unit: requests # factor to convert per time to per f.unit
       inputs:
         - timestamp: 2023-07-06T00:00
           duration: 3600

package/manifests/plugins/sci/success.yml

@@ -16,9 +16,6 @@ tree:
       pipeline:
         - sci
       config:
-        sci:
-          functional-unit-time: 1 sec
-          functional-unit: requests # factor to convert per time to per f.unit
       inputs:
         - timestamp: 2023-07-06T00:00
           duration: 3600

package/manifests/plugins/subtract/success.yml

@@ -0,0 +1,25 @@
+name: subtract demo
+description:
+tags:
+initialize:
+  outputs:
+    - yaml
+  plugins:
+    subtract:
+      method: Subtract
+      path: 'builtin'
+      global-config:
+        input-parameters: ['cpu/energy', 'network/energy']
+        output-parameter: 'energy/diff'
+tree:
+  children:
+    child:
+      pipeline:
+        - subtract
+      config:
+        subtract:
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 3600
+          cpu/energy: 0.003
+          network/energy: 0.001

package/manifests/plugins/sum/success.yml

@@ -2,7 +2,7 @@ name: sum
 description: successful path
 tags:
 initialize:
-  outputs: ['yaml']
+  # outputs: ['yaml']
   plugins:
     sum:
       method: Sum

package/package.json

@@ -1,14 +1,16 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "0.4.0-beta.1",
+  "version": "0.5.0-beta.0",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"
   },
   "bin": {
-    "ie": "./build/index.js",
-    "if-diff": "./build/diff.js"
+    "if-diff": "./build/diff.js",
+    "if-run": "./build/index.js",
+    "if-env": "./build/env.js",
+    "if-check": "./build/check.js"
   },
   "bugs": {
     "url": "https://github.com/Green-Software-Foundation/if/issues/new?assignees=&labels=feedback&projects=&template=feedback.md&title=Feedback+-+"
@@ -16,6 +18,7 @@
   "dependencies": {
     "@commitlint/cli": "^18.6.0",
     "@commitlint/config-conventional": "^18.6.0",
+    "@grnsft/if-core": "^0.0.10",
     "axios": "^1.7.2",
     "csv-parse": "^5.5.6",
     "csv-stringify": "^6.4.6",
@@ -36,6 +39,7 @@
     "@types/luxon": "^3.4.2",
     "@types/node": "^20.8.9",
     "axios-mock-adapter": "^1.22.0",
+    "cross-env": "7.0.3",
     "fixpack": "^4.0.0",
     "gts": "^5.0.0",
     "husky": "^8.0.0",
@@ -72,8 +76,10 @@
     "coverage": "jest --verbose --coverage --testPathPattern=src/__tests__/unit",
     "fix": "gts fix",
     "fix:package": "fixpack",
-    "ie": "npx ts-node src/index.ts",
+    "if-check": "cross-env CURRENT_DIR=$(node -p \"process.env.INIT_CWD\") npx ts-node src/check.ts",
     "if-diff": "npx ts-node src/diff.ts",
+    "if-env": "cross-env CURRENT_DIR=$(node -p \"process.env.INIT_CWD\") npx ts-node src/env.ts",
+    "if-run": "npx ts-node src/index.ts",
     "lint": "gts lint",
     "pre-commit": "lint-staged",
     "prepare": "husky install",

package/src/__mocks__/mock-manifest.yaml

@@ -0,0 +1,72 @@
+name: template manifest
+description: auto-generated template
+tags: null
+initialize:
+  plugins:
+    memory-energy-from-memory-util:
+      path: builtin
+      method: Coefficient
+      global-config:
+        input-parameter: memory/utilization
+        coefficient: 0.0001
+        output-parameter: memory/energy
+  outputs:
+    - yaml
+execution:
+  command: >-
+    /Users/manushak/.npm/_npx/1bf7c3c15bf47d04/node_modules/.bin/ts-node
+    /Users/manushak/Documents/Projects/Green-Software/if/src/index.ts -m
+    ./src/env-template.yml -o ./manifests/outputs/template
+  environment:
+    if-version: 0.4.0
+    os: macOS
+    os-version: 13.6.6
+    node-version: 20.12.2
+    date-time: 2024-06-18T08:39:55.771Z (UTC)
+    dependencies:
+      - "@babel/core@7.22.10"
+      - "@babel/preset-typescript@7.23.3"
+      - "@commitlint/cli@18.6.0"
+      - "@commitlint/config-conventional@18.6.0"
+      - "@grnsft/if-core@0.0.3"
+      - "@jest/globals@29.7.0"
+      - "@types/jest@29.5.8"
+      - "@types/js-yaml@4.0.9"
+      - "@types/luxon@3.4.2"
+      - "@types/node@20.9.0"
+      - axios-mock-adapter@1.22.0
+      - axios@1.7.2
+      - cross-env@7.0.3
+      - csv-parse@5.5.6
+      - csv-stringify@6.4.6
+      - fixpack@4.0.0
+      - gts@5.2.0
+      - husky@8.0.3
+      - jest@29.7.0
+      - js-yaml@4.1.0
+      - lint-staged@15.2.2
+      - luxon@3.4.4
+      - release-it@16.3.0
+      - rimraf@5.0.5
+      - ts-command-line-args@2.5.1
+      - ts-jest@29.1.1
+      - typescript-cubic-spline@1.0.1
+      - typescript@5.2.2
+      - winston@3.11.0
+      - zod@3.22.4
+  status: success
+tree:
+  children:
+    child:
+      pipeline:
+        - memory-energy-from-memory-util
+      config: null
+      inputs:
+        - timestamp: 2023-12-12T00:00:00.000Z
+          duration: 3600
+          memory/utilization: 10
+      outputs:
+        - timestamp: 2023-12-12T00:00:00.000Z
+          duration: 3600
+          memory/utilization: 10
+          memory/energy: 0.001

package/src/builtins/README.md

@@ -305,7 +305,7 @@ Then, you must select the metric you want to export to CSV. The name of that met
 For example, to export the `carbon` data from your tree to a CSV file:
 
 ```sh
-ie --manifest example.yml --output example#carbon
+if-run --manifest example.yml --output example#carbon
 ```
 
 This will save a CSV file called `example.csv`. The contents will look similar to the following:

package/src/builtins/coefficient/README.md

@@ -86,7 +86,25 @@ tree:
 You can run this example by saving it as `./examples/manifests/coefficient.yml` and executing the following command from the project root:
 
 ```sh
-ie --manifest ./examples/manifests/coefficient.yml --output ./examples/outputs/coefficient.yml
+if-run --manifest ./examples/manifests/coefficient.yml --output ./examples/outputs/coefficient.yml
 ```
 
 The results will be saved to a new `yaml` file in `./examples/outputs`
+
+
+## Errors
+
+`Coefficient` exposes one of the IF error classes.
+
+### GlobalConfigError
+
+You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+
+The required parameters are:
+- `input-parameter`: this must be a string
+- `coefficient`: this must be a number
+- `output-parameter`: this must be a string
+
+You can fix this error by checking you are providing valid values for each parameter in the config.
+
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors

package/src/builtins/copy-param/README.md

@@ -0,0 +1,104 @@
+# Copy-param
+
+`copy-param` is a generic plugin that duplicates an existing parameter in the `input` data and assigns it to a new key. You can either keep or delete the original copied parameter. A common use case for this is to rename parameters in the `inputs` array.
+
+You provide the name of the value you want to copy, and a name to assign the copy to. You also toggle a `keep-existing` parameter to either persist or delete the original copied value.
+
+For example, you could copy `energy` into `energy-copy`, with `keep-existing=true`. In this case your inputs:
+
+```yaml
+- timestamp: "2023-12-12T00:00:13.000Z",
+  duration: 30,
+  energy: 30
+```
+
+would become
+
+```yaml
+- timestamp: "2023-12-12T00:00:13.000Z",
+  duration: 30,
+  energy: 30
+  energy-copy: 30
+```
+
+but with `keep-existing=false`, the same inputs would yield:
+
+```yaml
+- timestamp: "2023-12-12T00:00:13.000Z",
+  duration: 30,
+  energy-copy: 30
+```
+
+## Parameters
+
+### Config
+
+Three parameters are required in config: `from` and `to` and `keep-existing`.
+
+`from`: an array of strings. Each string should match an existing key in the `inputs` array
+`to`: a string defining the name to use to add the result of summing the input parameters to the output array.
+`keep-existing`: toggles whether to keep or delete the copied parameter (defined in `to`)
+
+### Inputs
+
+As with all plugins, `timestamp` and `duration` are required. The key passed to `from` must exist in the `input` data.
+
+## Returns
+
+The plugin adds a new parameter with the name defined in `to` to the `input` data.
+
+
+## Implementation
+
+To run the plugin, you must first create an instance of `Copy`. Then, you can call `execute()`.
+
+```typescript
+import { Copy } from ".";
+
+const plugin = Copy({ 'keep-existing': true, from: 'from-param', to: 'to-param' });
+
+const result = plugin.execute([{
+    timestamp: "2023-12-12T00:00:13.000Z",
+    duration: 30,
+    'from-param': 'hello',
+}])
+
+console.log(result)
+
+```
+
+## Example manifest
+
+IF users will typically call the plugin as part of a pipeline defined in a manifest file. In this case, instantiating the plugin is handled by and does not have to be done explicitly by the user. The following is an example manifest that calls `copy-param`:
+
+```yaml
+name: copy-param
+description:
+tags:
+initialize:
+  plugins:
+    copy-param:
+      path: builtin
+      method: Copy
+      global-config:
+        keep-existing: true
+        from: original
+        to: copy
+tree:
+  children:
+    child-1:
+      pipeline:
+        - copy-param
+      inputs:
+        - timestamp: "2023-12-12T00:00:00.000Z"
+          original: 'hello'
+
+```
+
+You can run this example by saving it as `./manifests/examples/copy.yml` and executing the following command from the project root:
+
+```sh
+if-run --manifest ./manifests/examples/copy.yml -s
+```
+
+The results will be displayed in the console.

package/src/builtins/csv-lookup/README.md

@@ -136,7 +136,45 @@ You can run this example by saving it as `./examples/manifests/csv-lookup.yml` a
 
 ```sh
 npm i -g @grnsft/if
-ie --manifest manifests/plugins/csv-lookup.yml --output manifests/outputs/csv-lookup
+if-run --manifest manifests/plugins/csv-lookup.yml --output manifests/outputs/csv-lookup
 ```
 
 The results will be saved to a new `yaml` file in `manifests/outputs`.
+
+
+## Errors
+
+Coefficient exposes six of the IF error classes.
+
+### FetchingFileError
+
+This error is caused by problems finding the file at the path provided in the `filepath`. If the file is on your local filesystem, you can check that the file is definitely there. For a remote file, check your internet connection. You can check your connection to the server using a tool such as `ping` or `curl`. if you still experience problems, you could retrieve the remote file onto your local filesystem using a tool such as `wget`.
+
+### ReadFileError,
+
+This error is caused by problems reading the CSV file provided in the `filepath`. To fix it, check that the file contains valid CSV data. The file should have a `.csv` file extension and the data inside should be formatted correctly.
+
+### MissingCSVColumnError,
+
+This error is caused by `CsvLookup` failing to find a column in the CSV file whose name matches what was provided in `query`. To debug, check that you do not have any typos in your `query` and confirm that the requested column name definitely exists in the target file.
+
+### QueryDataNotFoundError,
+
+This error is caused by the `CsvLookup` plugin failing to find data that matches your query. Try revising your query parameters.
+
+### CSVParseError,
+
+This error arises due to problems parsing CSV data into IF. This can occur when the CSV data is incorrectly formatted or contains unexpected characters that IF does not recognize. These errors are expected to be unusual edge cases as incorrectly formatted data will usually be identified during file loading and cause a `ReadFileError`. To debug, check your CSV file for any unexpected formatting or unusual characters.
+
+### GlobalConfigError
+
+You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+
+The required parameters are:
+- `filepath`: This must be a path to a csv file
+- `query`: this must be an array of key-value pairs where the key is a string containing a column name an the value is a string containing the name of a value in `inputs`
+- `output`: this must be a string containing a name or a wildcard character (`"*"`)
+
+You can fix this error by checking you are providing valid values for each parameter in the config.
+
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors

package/src/builtins/divide/README.md

@@ -4,8 +4,6 @@
 
 You provide the names of the values you want to divide, and a name to use to add the divide to the output array.
 
-For example, `boavizta-cpu` need `cpu/number-cores` to work, however `cloud-metadata` returns `vcpus-allocated`, to get number of cores you divide `vcpus-allocated` by 2.
-
 ## Parameters
 
 ### Plugin config
@@ -26,6 +24,8 @@ For example, `boavizta-cpu` need `cpu/number-cores` to work, however `cloud-meta
 
 The plugin throws an exception if the division result is not a number.
 
+>Note: Plugin will warn and return `numerator` value in case if `denominator` is zero.
+
 ## Calculation
 
 ```pseudocode
@@ -89,7 +89,33 @@ You can run this example by saving it as `./examples/manifests/divide.yml` and e
 
 ```sh
 npm i -g @grnsft/if
-ie --manifest ./examples/manifests/divide.yml --output ./examples/outputs/divide.yml
+if-run --manifest ./examples/manifests/divide.yml --output ./examples/outputs/divide.yml
 ```
 
 The results will be saved to a new `yaml` file in `./examples/outputs`.
+
+## Errors
+
+`Divide` exposes two of IF's error classes.
+
+### GlobalConfigError
+
+You will receive an error starting `GlobalConfigError: ` if you have not provided the expected configuration data in the plugin's `initialize` block.
+
+The required parameters are:
+- `numerator`: a string containing the name of the input parameter whose value should be divided by `denominator`
+- `denominator`: a number to use as the denominator
+- ``output`: a string containing the name to assign the result of the division
+
+You can fix this error by checking you are providing valid values for each parameter in the config.
+
+### `MissingInputDataError`
+
+This error arises when a necessary piece of input data is missing from the `inputs` array.
+Every element in the ``inputs` array must contain:
+- `timestamp`
+- `duration`
+- whatever value you passed to `numerator`
+
+
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors

package/src/builtins/exponent/README.md

@@ -91,7 +91,27 @@ You can run this example by saving it as `manifests/examples/test/exponent.yml`
 
 ```sh
 npm i -g @grnsft/if
-ie --manifest manifests/examples/test/exponent.yml --output manifests/outputs/exponent.yml
+if-run --manifest manifests/examples/test/exponent.yml --output manifests/outputs/exponent.yml
 ```
 
 The results will be saved to a new `yaml` file in `manifests/outputs`.
+
+## Errors
+
+`Exponent` exposes two of IF's error classes.
+
+### `MissingInputDataError`
+
+This error arises when a necessary piece of input data is missing from the `inputs` array.
+Every element in the `inputs` array must contain:
+
+- `timestamp`
+- `duration`
+- whatever value you passed to `input-parameter`
+
+
+### `InputValidationError`
+
+This error arises when an invalid value is passed to `Exponent`. Typically, this can occur when a non-numeric value (such as a string made of alphabetic characters) is passed where a number or numeric string is expected. Please check that the types are correct for all the relevant fields in your `inputs` array.
+
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors