@grnsft/if 0.5.0 → 0.6.0-beta.0

package/manifests/outputs/pipelines/teads-curve.yaml

@@ -0,0 +1,188 @@
+name: carbon-intensity plugin demo
+description: null
+tags: null
+initialize:
+  plugins:
+    interpolate:
+      path: builtin
+      method: Interpolation
+      global-config:
+        method: linear
+        x:
+          - 0
+          - 10
+          - 50
+          - 100
+        'y':
+          - 0.12
+          - 0.32
+          - 0.75
+          - 1.02
+        input-parameter: cpu/utilization
+        output-parameter: cpu-factor
+    cpu-factor-to-wattage:
+      path: builtin
+      method: Multiply
+      global-config:
+        input-parameters:
+          - cpu-factor
+          - thermal-design-power
+        output-parameter: cpu-wattage
+    wattage-times-duration:
+      path: builtin
+      method: Multiply
+      global-config:
+        input-parameters:
+          - cpu-wattage
+          - duration
+        output-parameter: cpu-wattage-times-duration
+    wattage-to-energy-kwh:
+      path: builtin
+      method: Divide
+      global-config:
+        numerator: cpu-wattage-times-duration
+        denominator: 3600000
+        output: cpu-energy-raw
+    calculate-vcpu-ratio:
+      path: builtin
+      method: Divide
+      global-config:
+        numerator: vcpus-total
+        denominator: vcpus-allocated
+        output: vcpu-ratio
+    correct-cpu-energy-for-vcpu-ratio:
+      path: builtin
+      method: Divide
+      global-config:
+        numerator: cpu-energy-raw
+        denominator: vcpu-ratio
+        output: cpu-energy-kwh
+execution:
+  command: >-
+    /Users/mariamkhalatova/.npm/_npx/1bf7c3c15bf47d04/node_modules/.bin/ts-node
+    /Users/mariamkhalatova/Projects/UK/if/src/if-run/index.ts -m
+    manifests/examples/pipelines/teads-curve.yml -o
+    manifests/outputs/pipelines/teads-curve
+  environment:
+    if-version: 0.5.0
+    os: macOS
+    os-version: '14.5'
+    node-version: 18.14.2
+    date-time: 2024-07-19T06:35:33.728Z (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.10'
+      - '@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:
+        compute:
+          - interpolate
+          - cpu-factor-to-wattage
+          - wattage-times-duration
+          - wattage-to-energy-kwh
+          - calculate-vcpu-ratio
+          - correct-cpu-energy-for-vcpu-ratio
+      defaults:
+        thermal-design-power: 100
+        vcpus-total: 8
+        vcpus-allocated: 2
+      inputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 360
+          cpu/utilization: 1
+          carbon: 30
+        - timestamp: 2023-09-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 10
+        - timestamp: 2023-10-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 50
+        - timestamp: 2023-10-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 100
+      outputs:
+        - timestamp: 2023-08-06T00:00
+          duration: 360
+          cpu/utilization: 1
+          carbon: 30
+          thermal-design-power: 100
+          vcpus-total: 8
+          vcpus-allocated: 2
+          cpu-factor: 0.13999999999999999
+          cpu-wattage: 13.999999999999998
+          cpu-wattage-times-duration: 5039.999999999999
+          cpu-energy-raw: 0.0013999999999999998
+          vcpu-ratio: 4
+          cpu-energy-kwh: 0.00034999999999999994
+        - timestamp: 2023-09-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 10
+          thermal-design-power: 100
+          vcpus-total: 8
+          vcpus-allocated: 2
+          cpu-factor: 0.32
+          cpu-wattage: 32
+          cpu-wattage-times-duration: 11520
+          cpu-energy-raw: 0.0032
+          vcpu-ratio: 4
+          cpu-energy-kwh: 0.0008
+        - timestamp: 2023-10-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 50
+          thermal-design-power: 100
+          vcpus-total: 8
+          vcpus-allocated: 2
+          cpu-factor: 0.75
+          cpu-wattage: 75
+          cpu-wattage-times-duration: 27000
+          cpu-energy-raw: 0.0075
+          vcpu-ratio: 4
+          cpu-energy-kwh: 0.001875
+        - timestamp: 2023-10-06T00:00
+          duration: 360
+          carbon: 30
+          cpu/utilization: 100
+          thermal-design-power: 100
+          vcpus-total: 8
+          vcpus-allocated: 2
+          cpu-factor: 1.02
+          cpu-wattage: 102
+          cpu-wattage-times-duration: 36720
+          cpu-energy-raw: 0.0102
+          vcpu-ratio: 4
+          cpu-energy-kwh: 0.00255

package/manifests/outputs/pipelines/zeros.yaml

@@ -0,0 +1,198 @@
+name: generics
+description: >-
+  a pipeline that does arbitrary calculations using our generic arithmetic
+  builtins
+tags: null
+initialize:
+  plugins:
+    sum-zero-and-one:
+      path: builtin
+      method: Sum
+      global-config:
+        input-parameters:
+          - some-value
+          - zero-value
+        output-parameter: one-plus-zero
+    sum-zero-and-zero:
+      path: builtin
+      method: Sum
+      global-config:
+        input-parameters:
+          - zero-value
+          - zero-value
+        output-parameter: zero-plus-zero
+    subtract-one-and-zero:
+      path: builtin
+      method: Subtract
+      global-config:
+        input-parameters:
+          - some-value
+          - zero-value
+        output-parameter: one-minus-zero
+    subtract-zero-and-zero:
+      path: builtin
+      method: Sum
+      global-config:
+        input-parameters:
+          - zero-value
+          - zero-value
+        output-parameter: zero-minus-zero
+    subtract-zero-and-one:
+      path: builtin
+      method: Subtract
+      global-config:
+        input-parameters:
+          - zero-value
+          - some-value
+        output-parameter: zero-minus-one
+    coefficient-one-times-zero:
+      path: builtin
+      method: Coefficient
+      global-config:
+        input-parameter: zero-value
+        coefficient: 1
+        output-parameter: zero-times-one-coefficient
+    coefficient-zero-times-one:
+      path: builtin
+      method: Coefficient
+      global-config:
+        input-parameter: some-value
+        coefficient: 0
+        output-parameter: one-times-zero-coefficient
+    coefficient-zero-times-zero:
+      path: builtin
+      method: Coefficient
+      global-config:
+        input-parameter: zero-value
+        coefficient: 0
+        output-parameter: zero-times-zero-coefficient
+    multiply-one-times-zero:
+      path: builtin
+      method: Multiply
+      global-config:
+        input-parameters:
+          - some-value
+          - zero-value
+        output-parameter: one-times-zero
+    multiply-zero-times-one:
+      path: builtin
+      method: Multiply
+      global-config:
+        input-parameters:
+          - zero-value
+          - zero-value
+        output-parameter: zero-times-one
+    exponent-one-to-zero:
+      path: builtin
+      method: Exponent
+      global-config:
+        input-parameter: some-value
+        exponent: 0
+        output-parameter: one-raised-to-zero-power
+    exponent-zero-to-zero:
+      path: builtin
+      method: Exponent
+      global-config:
+        input-parameter: zero-value
+        exponent: 0
+        output-parameter: zero-raised-to-zero-power
+    exponent-zero-to-one:
+      path: builtin
+      method: Exponent
+      global-config:
+        input-parameter: zero-value
+        exponent: 1
+        output-parameter: zero-raised-to-first-power
+    sci:
+      path: builtin
+      method: Sci
+      global-config:
+        functional-unit: zero-value
+execution:
+  command: >-
+    /Users/mariamkhalatova/.npm/_npx/1bf7c3c15bf47d04/node_modules/.bin/ts-node
+    /Users/mariamkhalatova/Projects/UK/if/src/if-run/index.ts -m
+    manifests/examples/pipelines/zeros.yml -o manifests/outputs/pipelines/zeros
+  environment:
+    if-version: 0.5.0
+    os: macOS
+    os-version: '14.5'
+    node-version: 18.14.2
+    date-time: 2024-07-19T06:36:00.790Z (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.10'
+      - '@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-1:
+      pipeline:
+        compute:
+          - sum-zero-and-one
+          - sum-zero-and-zero
+          - subtract-one-and-zero
+          - subtract-zero-and-zero
+          - subtract-zero-and-one
+          - coefficient-one-times-zero
+          - coefficient-zero-times-one
+          - coefficient-zero-times-zero
+          - multiply-one-times-zero
+          - multiply-zero-times-one
+          - exponent-one-to-zero
+          - exponent-zero-to-one
+          - exponent-zero-to-zero
+          - sci
+      inputs:
+        - timestamp: '2023-12-12T00:00:00.000Z'
+          duration: 1
+          some-value: 1
+          zero-value: 0
+          carbon: 10
+      outputs:
+        - timestamp: '2023-12-12T00:00:00.000Z'
+          duration: 1
+          some-value: 1
+          zero-value: 0
+          carbon: 10
+          one-plus-zero: 1
+          zero-plus-zero: 0
+          one-minus-zero: 1
+          zero-minus-zero: 0
+          zero-minus-one: -1
+          zero-times-one-coefficient: 0
+          one-times-zero-coefficient: 0
+          zero-times-zero-coefficient: 0
+          one-times-zero: 0
+          zero-times-one: 0
+          one-raised-to-zero-power: 1
+          zero-raised-to-first-power: 0
+          zero-raised-to-zero-power: 1
+          sci: 10

package/package.json

@@ -1,16 +1,17 @@
 {
   "name": "@grnsft/if",
   "description": "Impact Framework",
-  "version": "0.5.0",
+  "version": "0.6.0-beta.0",
   "author": {
     "name": "Green Software Foundation",
     "email": "info@gsf.com"
   },
   "bin": {
-    "if-diff": "./build/diff.js",
-    "if-run": "./build/index.js",
-    "if-env": "./build/env.js",
-    "if-check": "./build/check.js"
+    "if-diff": "./build/if-diff/index.js",
+    "if-run": "./build/if-run/index.js",
+    "if-env": "./build/if-env/index.js",
+    "if-check": "./build/if-check/index.js",
+    "if-csv": "./build/if-csv/index.js"
   },
   "bugs": {
     "url": "https://github.com/Green-Software-Foundation/if/issues/new?assignees=&labels=feedback&projects=&template=feedback.md&title=Feedback+-+"
@@ -18,7 +19,7 @@
   "dependencies": {
     "@commitlint/cli": "^18.6.0",
     "@commitlint/config-conventional": "^18.6.0",
-    "@grnsft/if-core": "^0.0.10",
+    "@grnsft/if-core": "^0.0.16",
     "axios": "^1.7.2",
     "csv-parse": "^5.5.6",
     "csv-stringify": "^6.4.6",
@@ -63,7 +64,6 @@
     "models"
   ],
   "license": "MIT",
-  "main": "build/index.js",
   "publishConfig": {
     "access": "public"
   },
@@ -73,21 +73,20 @@
   "scripts": {
     "build": "npm run clean && tsc --project tsconfig.build.json",
     "clean": "rimraf build/",
-    "coverage": "jest --verbose --coverage --testPathPattern=src/__tests__/unit",
+    "coverage": "jest --verbose --coverage --testPathPattern=src/__tests__/",
     "fix": "gts fix",
     "fix:package": "fixpack",
-    "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",
+    "if-check": "cross-env CURRENT_DIR=$(node -p \"process.env.INIT_CWD\") npx ts-node src/if-check/index.ts",
+    "if-csv": "cross-env CURRENT_DIR=$(node -p \"process.env.INIT_CWD\") npx ts-node src/if-csv/index.ts",
+    "if-diff": "npx ts-node src/if-diff/index.ts",
+    "if-env": "cross-env CURRENT_DIR=$(node -p \"process.env.INIT_CWD\") npx ts-node src/if-env/index.ts",
+    "if-run": "npx ts-node src/if-run/index.ts",
     "lint": "gts lint",
     "pre-commit": "lint-staged",
     "prepare": "husky install",
     "prepublish": "npm run build",
     "release": "release-it",
-    "test": "jest --verbose --testPathPattern=src/__tests__/unit",
-    "test:integration": "jest --verbose --testPathPattern=src/__tests__/integration"
+    "test": "jest --verbose --testPathPattern=src/__tests__/"
   },
-  "stability": "stable",
-  "types": "src/index.d.ts"
+  "stability": "stable"
 }

package/src/__mocks__/mock-manifest.yaml

@@ -10,8 +10,6 @@ initialize:
         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
@@ -59,7 +57,8 @@ tree:
   children:
     child:
       pipeline:
-        - memory-energy-from-memory-util
+        compute:
+          - memory-energy-from-memory-util
       config: null
       inputs:
         - timestamp: 2023-12-12T00:00:00.000Z

package/src/{config → if-env/config}/env-template.yml

@@ -2,8 +2,6 @@ name: template manifest # rename me!
 description: auto-generated template # update description!
 tags: # add any tags that will help you to track your manifests
 initialize:
-  outputs:
-    - yaml # you can add - csv to export to csv
   plugins: # add more plugins for your use-case
     memory-energy-from-memory-util: # you can name this any way you like!
       method: Coefficient # the name of the function exported from the plugin
@@ -16,7 +14,8 @@ tree:
   children: # add a chile for each distinct component you want to measure
     child:
       pipeline: # the pipeline is an ordered list of plugins you want to execute
-        - memory-energy-from-memory-util # must match the name in initialize!
+        compute:
+          - memory-energy-from-memory-util # must match the name in initialize!
       config: # any plugin specific, node-level config
       inputs:
         - timestamp: 2023-12-12T00:00:00.000Z # ISO 8061 string

package/src/{builtins → if-run/builtins}/coefficient/README.md

@@ -16,6 +16,22 @@ Three parameters are required in global config: `input-parameter`, `coefficient`
 - `coefficient`: the value to multiply `input-parameter` by.
 - `output-parameter`: a string defining the name to use to add the product of the input parameters to the output array.
 
+### Plugin parameter metadata
+
+The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method`
+of the parameters of the inputs and outputs
+
+- `inputs`: describe parameters of the `input-parameter` of the global config. Each parameter has:
+
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+
+- `outputs`: describe parameters of the `output-parameter` of the global config. Each parameter has:
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+
 ### Inputs
 
 All of `input-parameters` must be available in the input array.
@@ -53,15 +69,13 @@ const result = coeff.execute([
 
 ## 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 `ie` and does not have to be done explicitly by the user. The following is an example manifest that calls `coefficient`:
+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 `if-run` and does not have to be done explicitly by the user. The following is an example manifest that calls `coefficient`:
 
 ```yaml
 name: coefficient-demo
 description:
 tags:
 initialize:
-  outputs:
-    - yaml
   plugins:
     coefficient:
       method: Coefficient
@@ -70,13 +84,21 @@ initialize:
         input-parameter: 'carbon'
         coefficient: 3
         output-parameter: 'carbon-product'
+       parameter-metadata:
+        inputs:
+          carbon:
+            description: "an amount of carbon emitted into the atmosphere"
+            unit: "gCO2e"
+        outputs:
+          carbon-product:
+            description: "a product of cabon property and the coefficient"
+            unit: "gCO2e"
 tree:
   children:
     child:
       pipeline:
-        - coefficient
-      config:
-        coefficient:
+        compute:
+          - coefficient
       inputs:
         - timestamp: 2023-08-06T00:00
           duration: 3600
@@ -86,12 +108,11 @@ tree:
 You can run this example by saving it as `./examples/manifests/coefficient.yml` and executing the following command from the project root:
 
 ```sh
-if-run --manifest ./examples/manifests/coefficient.yml --output ./examples/outputs/coefficient.yml
+if-run --manifest ./examples/manifests/coefficient.yml --output ./examples/outputs/coefficient
 ```
 
 The results will be saved to a new `yaml` file in `./examples/outputs`
 
-
 ## Errors
 
 `Coefficient` exposes one of the IF error classes.
@@ -101,10 +122,11 @@ The results will be saved to a new `yaml` file in `./examples/outputs`
 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
+For more information on our error classes, please visit [our docs](https://if.greensoftware.foundation/reference/errors)

package/src/{builtins → if-run/builtins}/copy-param/README.md

@@ -39,6 +39,21 @@ Three parameters are required in config: `from` and `to` and `keep-existing`.
 `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`)
 
+### Plugin parameter metadata
+
+The `parameter-metadata` section contains information about `description`, `unit` and `aggregation-method` of the parameters of the inputs and outputs
+
+- `inputs`: describe the parameter of the `from` of the global config. The parameter has the following attributes:
+
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+
+- `outputs`: describe the parameters of the `to` of the global config. The parameter has the following attributes:
+  - `description`: description of the parameter
+  - `unit`: unit of the parameter
+  - `aggregation-method`: aggregation method of the parameter (it can be `sum`, `avg` or `none`)
+
 ### Inputs
 
 As with all plugins, `timestamp` and `duration` are required. The key passed to `from` must exist in the `input` data.
@@ -47,24 +62,28 @@ As with all plugins, `timestamp` and `duration` are required. The key passed to
 
 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 ".";
+import {Copy} from '.';
 
-const plugin = Copy({ 'keep-existing': true, from: 'from-param', to: 'to-param' });
+const plugin = Copy({
+  'keep-existing': true,
+  from: 'from-param',
+  to: 'to-param',
+});
 
-const result = plugin.execute([{
-    timestamp: "2023-12-12T00:00:13.000Z",
+const result = plugin.execute([
+  {
+    timestamp: '2023-12-12T00:00:13.000Z',
     duration: 30,
     'from-param': 'hello',
-}])
-
-console.log(result)
+  },
+]);
 
+console.log(result);
 ```
 
 ## Example manifest
@@ -88,11 +107,11 @@ tree:
   children:
     child-1:
       pipeline:
-        - copy-param
+        compute:
+          - copy-param
       inputs:
-        - timestamp: "2023-12-12T00:00:00.000Z"
+        - 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: