Merge branch 'main' into AI-touchups

Author: PavelLinearB

docs/automation-actions.md

@@ -365,13 +365,13 @@ This action, once triggered, will start a workflow dispatch automation with the
 
 | Args                    | Usage    | Type   | Description                                                                                                                                                                                                                             |
 | ----------------------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `workflow`              | Required | String | The ID or name of the workflow dispatch.                                                                                                                                                                                                |
-| `owner`                 | Optional | String | By default, the value of `repo.owner` context variable. The account owner of the repository. Case insensitive.                                                                                                                          |
-| `repo`                  | Optional | String | By default, the value of `repo.name` context variable. The name of the repository without the `.git` extension. Case insensitive.                                                                                                       |
-| `ref`                   | Optional | String | By default, the value of `branch.name` context variable. The account owner of the repository. Case insensitive.                                                                                                                         |
+| `workflow`              | Required | String | The ID or the path of the workflow dispatch.                                                                                                                                                                                            |
+| `owner`                 | Optional | String | By default, the value of `repo.owner` context variable. The account owner of the repository. Case insensitive.                                                                                                                      |
+| `repo`                  | Optional | String | By default, the value of `repo.name` context variable. The name of the repository without the `.git` extension. Case insensitive.                                                                                                      |
+| `ref`                   | Optional | String | By default, the value of `branch.name` context variable. The branch name. Case sensitive.                                                                                                                                               |
 | `inputs`                | Optional | String | By default, an empty list. Key-Value list with the arguments to provide to the workflow                                                                                                                                                 |
 | `check_name`            | Optional | String | When added, after the workflow is complete, add the check name to the checks list on GitHub                                                                                                                                             |
-| `stop_ongoing_workflow` | Optional | Bool   | By default, `false`. In case the workflow already runs on the branch, if `true`: cancel the ongoing workflow before running the newly dispatched workflow. If `false`: wait for the old workflow to finish before dispatching a new one |
+| `stop_ongoing_workflow` | Optional | Bool   | By default, `false`. If the workflow already runs on the branch, When `true`: cancel the ongoing workflow before running the newly dispatched workflow. When `false`: wait for the old workflow to finish before dispatching a new one |
 
 </div>
 
@@ -397,8 +397,9 @@ has:
 
 !!! attention
 
-  	* This action will invoke the run of a workflow dispatch; thus, it might result in significant GitHub action minutes charge.
+  	* This action will invoke the run of a workflow dispatch; thus, it might result in a significant GitHub action minutes charge.
   	* We encourage you to use this action with [custom triggers](./execution-model.md#explicit-triggers)
+   	* To manually test the webhook dispatch, please [run the workflow](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/manually-running-a-workflow#running-a-workflow){:target="_blank"} before using it with gitStream.
 
 #### `send-http-request` :fontawesome-brands-github:
 

docs/execution-model.md

@@ -26,11 +26,9 @@ Triggers can be defined globally at the file level or specifically for each auto
 
 #### `triggers` section
 
-Use explicit triggers to enhance the control and customization of automations in gitStream, when you need to define precisely when and how automations should be triggered based on various events and actions within pull requests.
+The `triggers` section in gitStream gives you precise control over when automations execute. It allows you to define conditions based on pull request events using `include` and `exclude` lists to specify branch and repository patterns. These lists determine which branches or repositories trigger or bypass automation but do not affect the events initiating automations.
 
-The `triggers` is section specifies when automations are executed, supporting `include` and `exclude` lists for branch and repository patterns at the file level.
-
-The `on` keyword can also be used within individual automations to define specific events that trigger those automations. Add the `on` keyword under the `triggers` key in the file and/or to a specific automation to define explicit triggers.
+Additionally, the `on` keyword defines specific events that trigger automations. It can be added at the file level (under the `triggers` section) or within individual automations for greater customization. Multiple triggers can be stacked, meaning gitStream will execute the automation for each matching triggering event, allowing flexibility in defining automation behavior
 
 | Key                                                   | Type              | Description                                                    |
 | ----------------------------------------------------- | ----------------- | -------------------------------------------------------------- |
@@ -56,6 +54,7 @@ The table below lists supported explicit triggers, categorized into those enable
 | :fontawesome-brands-github: Transition from draft to ready for review | `pr_ready_for_review`                        | `off`                          |
 | :fontawesome-brands-github: transition from any state to closed       | `pr_closed`                                  | `off`                          |
 | :fontawesome-brands-github: transition from closed to open            | `pr_reopened`                                | `off`                          |
+| :fontawesome-brands-github: Transition from any state to approved     | `pr_approved`                                | If there is an automation with one of the actions: `require-reviewers`, `set-required-approvals` or `merge`, or uses `pr.approvals` context variable  |
 
 Explicit triggers are set independently per each automation block and can be configured at the file level, specific to each automation separately or in combination. If triggers are listed at the file level **and** specific automation, the automation will be triggered according to both triggers.
 If an automation block does not have explicit triggers configured, it will be triggered according to the default (implicit) triggers.
@@ -72,7 +71,7 @@ If an automation block does not have explicit triggers configured, it will be tr
 
 **Exclude/Include prioritization**
 
-- Exclude overrides the include option. Thus, a repo will be excluded when a it matches both the include and exclude lists.
+- Exclude overrides the include option. Thus, a repo will be excluded when it matches the include and exclude lists.
 
     In the following example, the automations in the file will be triggered for all repositories that contain the string `feature`, except for the repository `my_feature`
     ```yaml+jinja
@@ -89,7 +88,7 @@ If an automation block does not have explicit triggers configured, it will be tr
 
 #### Dependabot and Renovate
 
-For example, you can have your normal automations that help developers with their PRs and a separate automation that automates Dependabot or Renovate version bumps. Both automations serve distinctly different purposes: the first helps your developers streamline their PRs, while the other reduces developers' toil by auto-approving version bumps. You will not want to trigger gitStream for Dependabot or Renovate unnecessarily, so you can configure the triggers to exclude the branch where Dependabot or Renovate PRs are created.
+For example, you can have your normal automations that help developers with their PRs and a separate automation that automates Dependabot or Renovate version bumps. Both automations serve distinctly different purposes: the first helps your developers streamline their PRs, while the other reduces developers' toil by auto-approving version bumps. You will not want to unnecessarily trigger gitStream for Dependabot or Renovate, so you can configure the triggers to exclude the branch where Dependabot or Renovate PRs are created.
 
 !!! warning "Required gitStream Plugins"
     This example requires you to install the [`extractDependabotVersionBump`](/filter-function-plugins/#extractdependabotversionbump) and [`compareSemver`](/filter-function-plugins/#comparesemver) plugins.

docs/filter-functions.md

@@ -20,7 +20,7 @@ The following functions are supported in addition to the built-in functions prov
 
 | Function                                                                                                       | Input                  | Args                            | Output                 |
 | -------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------- | ---------------------- |
-| [`capture`](#capture)<br />Find and return the first occurrence of a regex in the input string                 | String                 | `regex`                         | [Objects]              |
+| [`capture`](#capture)<br />Find and return the first occurrence of a regex in the input string                 | String                 | `regex`                         | String              |
 | [`difference`](#difference)<br />Given two lists, keep only items that are in the 1st list but not in the 2nd. | [Objects]              | `list`                          | [Objects]              |
 | [`every`](#every)<br />Checks whether all element in the list are `true`                                       | [Bool]                 | -                               | Bool                   |
 | [`filter`](#filter)<br />Reduce list of items into a list of same items that match the specified term          | [String]<br />[Object] | `regex`, `term`, `list`, `attr` | [String]<br />[Object] |
@@ -94,7 +94,7 @@ Extract the first match of the regex in the input string. If no match is found,
 | -------- | ---------|-----------|------------------------------------------------ |
 | - | Input  | String    | The string to find the match in |
 | `regex`  | Input |  String  | Search term to match with the input string |
-| -  | Output  | Bool   | The first substring that match the provided regex |
+| -  | Output  | String   | The first substring that matches the provided regex |
 
 </div>
 

plugins/filters/askAI/index.js

@@ -8,9 +8,11 @@
  * @returns {Object} Returns the response from the AI model.
  * @example {{ branch | generateDescription(pr, repo, source) }}
  * @license MIT
-**/
+ * */
 
-const lockFiles = [
+const MAX_TOKENS = 4096;
+const OPEN_AI_ENDPOINT = 'https://api.openai.com/v1/chat/completions';
+const LOCK_FILES = [
   'package-lock.json',
   'yarn.lock',
   'npm-shrinkwrap.json',
@@ -36,8 +38,7 @@ const lockFiles = [
   'flake.lock',
   'pnpm-lock.yaml'
 ];
-
-const excludeExpressionsList = [
+const EXCLUDE_EXPRESSIONS_LIST = [
   '.*\\.(ini|csv|xls|xlsx|xlr|doc|docx|txt|pps|ppt|pptx|dot|dotx|log|tar|rtf|dat|ipynb|po|profile|object|obj|dxf|twb|bcsymbolmap|tfstate|pdf|rbi|pem|crt|svg|png|jpeg|jpg|ttf)$',
   '.*(package-lock|packages\\.lock|package)\\.json$',
   '.*(yarn|gemfile|podfile|cargo|composer|pipfile|gopkg)\\.lock$',
@@ -47,55 +48,58 @@ const excludeExpressionsList = [
   '.*public/assets/.*\\.js',
   '.*ci\\.yml$'
 ];
+const IGNORE_FILES_REGEX_LIST = [
+  ...LOCK_FILES.map(f => f.replace('.', '\\.')),
+  ...EXCLUDE_EXPRESSIONS_LIST
+];
+const EXCLUDE_PATTERN = new RegExp(IGNORE_FILES_REGEX_LIST.join('|'));
 
-const ignoreFilesRegexList = lockFiles
-  .map(file => file.replace('.', '\\.'))
-  .concat(excludeExpressionsList);
-const excludePattern = new RegExp(ignoreFilesRegexList.join('|'));
-
-const filterExcludeFiles = file => {
-  return !excludePattern.test(file) || (file.diff?.split(' ').length ?? 0) < 800;
-};
-
-const buildArrayContext = context => {
-  return context.filter(element => {
-    if (typeof element !== 'object') {
-      return true;
-    }
-
-    return context.filter(filterExcludeFiles);
-  });
+/**
+ * @description Check if a file should be excluded from the context like "package-lock.json"
+ * @param {*} fileObject
+ * @returns returns true if the file should be excluded
+ */
+const shouldExcludeFile = fileObject => {
+  const shouldExludeByName = EXCLUDE_PATTERN.test(fileObject.original_file);
+  const shouldExludeBySize = (fileObject.diff?.split(' ').length ?? 0) > 1000;
+
+  return shouldExludeByName || shouldExludeBySize;
 };
 
-const buildSourceContext = context => {
-  return context.diff.files.filter(filterExcludeFiles);
+/**
+ * @description Check if a file should be included in the context
+ * @param {*} fileObject
+ * @returns returns true if the file should be included
+ */
+const shouldIncludeFile = fileObject => {
+  return !shouldExcludeFile(fileObject);
 };
 
 const buildContextForGPT = context => {
   if (Array.isArray(context)) {
-    return buildArrayContext(context);
+    return context.filter(element =>
+      typeof element !== 'object' ? true : context.filter(shouldIncludeFile)
+    );
   }
 
   if (context?.diff?.files) {
-    return buildSourceContext(context);
+    const files = context.diff.files.filter(shouldIncludeFile);
+    return files;
   }
 
   return context;
 };
 
-const askAI = async (context, role = '', prompt, token, callback) => {
-  const cacheKey = `${__filename}${role}${prompt}`;
-  
-  if (process.env[cacheKey]) {
-    return callback(null, process.env[cacheKey]);
-  }
-
-  const maxTokens = 4096;
-  const endpoint = 'https://api.openai.com/v1/chat/completions';
-
+const askAI = async (context, role, prompt, token, callback) => {
   const formattedContext = buildContextForGPT(context);
 
-  const response = await fetch(endpoint, {
+  if (!formattedContext?.length) {
+    const message = `There are no context files to analyze.\nAll ${context?.diff?.files?.length} files were excluded by pattern or size.`;
+    console.log(message);
+    return callback(null, message);
+  }
+
+  const response = await fetch(OPEN_AI_ENDPOINT, {
     method: 'POST',
     headers: {
       'Content-Type': 'application/json',
@@ -104,32 +108,32 @@ const askAI = async (context, role = '', prompt, token, callback) => {
     body: JSON.stringify({
       model: 'gpt-4o-2024-08-06',
       messages: [
-        ...(role ? 
-        [
-          {
-            role: 'system',
-            content: `You are a ${role}. Answer only to the request, without any introductory or conclusion text.`
-          }] 
-          : []),
+        {
+          role: 'system',
+          content: `You are a ${role}. Answer only to the request, without any introductory or conclusion text.`
+        },
         {
           role: 'user',
           content: JSON.stringify(formattedContext)
         },
         { role: 'user', content: prompt }
       ],
-      max_tokens: maxTokens
+      max_tokens: MAX_TOKENS
     })
   });
 
   const data = await response.json();
 
+  if (data?.error?.message) {
+    console.error(data.error.message);
+    return callback(null, data.error.message);
+  }
+
   const suggestion =
     data.choices?.[0]?.message?.content ??
     'context was too big for api, try with smaller context object';
 
-  process.env[cacheKey] = suggestion;
-
-  return callback(null, process.env[cacheKey]);
+  return callback(null, suggestion);
 };
 
 module.exports = {