Flow AI documentation (#994)

* Prompt archi refactoring * AI documentation & diff v0 * fix * fix * doc * changelog * fixes * changelog * cspell * [Mega-Linter] Apply linters fixes :) --------- Co-authored-by: nvuillam <[email protected]>
hardisgroupcom · Jan 12, 2025 · 1002834 · 1002834
1 parent b1eef33
commit 1002834
Show file tree

Hide file tree

Showing 18 changed files with 359 additions and 62 deletions.
diff --git a/.github/linters/.cspell.json b/.github/linters/.cspell.json
@@ -25,6 +25,7 @@
         "Actv",
         "Administrateur",
         "Affero",
+        "Ajoutez",
         "Alainbates",
         "Astran",
         "Astro",
@@ -104,6 +105,7 @@
         "Keyfile",
         "Keyv",
         "Kvdb",
+        "L'erreur",
         "LISTVIEWNAME",
         "LVMYAA",
         "Licences",
@@ -182,18 +184,19 @@
         "Upsert",
         "VCAS",
         "VERSIONNUMBER",
+        "Veuillez",
         "Viewfile",
         "Visualforce",
         "Visualiser",
         "Vuillamy",
         "WIPO",
         "XSLX",
         "Xmls",
-        "Yahooo",
         "YOURDEVHUBUSERNAME",
         "YOURORGNAME",
         "YOURSOURCEORG",
         "YOURSOURCEORGUSERNAME",
+        "Yahooo",
         "ZWSAU",
         "accordionallowed",
         "accordionapex",
@@ -240,6 +243,7 @@
         "allowfullscreen",
         "allowpurgefailure",
         "allproperties",
+        "analyste",
         "antislashes",
         "apexlog",
         "apexp",
@@ -250,11 +254,13 @@
         "assigneduserstomobileconfig",
         "astran",
         "astrea",
+        "attributs",
         "audittrail",
         "authprovider",
         "authproviders",
         "autocleantypes",
         "autoplay",
+        "avant",
         "avec",
         "azdev",
         "badwords",
@@ -288,7 +294,9 @@
         "changedroleforuserfromnone",
         "changedroleforusertonone",
         "changedsenderemail",
+        "changements",
         "changemgmt",
+        "chang\u00e9",
         "checkcoverage",
         "checkcoverage) -- endArgs.indexOf(\"--checkcoverage\"",
         "checkonly",
@@ -304,16 +312,20 @@
         "columnify",
         "commandreference",
         "commandsstop",
+        "commencer",
         "commitlint",
         "commitmode",
         "commitsto",
+        "compris",
         "concat",
         "configfile",
         "confirmfreeze",
         "confirmunfreeze",
         "conta",
         "contentassets",
+        "contient",
         "coreutils",
+        "correctement",
         "correspondance",
         "cosmiconfig",
         "cours",
@@ -349,6 +361,7 @@
         "dfgdlf",
         "dhgfh",
         "difftool",
+        "diff\u00e9rences",
         "dimitrimonge",
         "dlrs",
         "dockerfilelintrc",
@@ -357,10 +370,14 @@
         "dompurify",
         "duplicatefiles",
         "d\u00e9commissionn\u00e9es",
+        "d\u00e9crire",
+        "d\u00e9ploiement",
+        "d\u00e9ploiements",
         "d\u00e9ployer",
         "d\u2019une",
         "eatre",
         "ects",
+        "effectuer",
         "elementsignored",
         "elgohr",
         "emailservices",
@@ -372,12 +389,14 @@
         "erroronwarnings",
         "errorprone",
         "eslintcache",
+        "espace",
         "eventtype",
         "everytime",
         "exceljs",
         "excludefilter",
         "excludeprofiles",
         "excludeusers",
+        "exemple",
         "expcloud",
         "explainability",
         "failiferror",
@@ -533,6 +552,7 @@
         "includemanaged",
         "includepackages",
         "includeprofiles",
+        "inclure",
         "initial",
         "initialisation",
         "inputfile",
@@ -549,11 +569,13 @@
         "integ",
         "interf",
         "interf\u00e8re",
+        "int\u00e9gr\u00e9",
         "isactive",
         "isbuildercontent",
         "isfrozen",
         "javascripts",
         "jeandupont",
+        "jetons",
         "jlsfgd",
         "jscpd",
         "jsforce",
@@ -564,6 +586,8 @@
         "keyv",
         "keyvalue",
         "kvdb",
+        "l'erreur",
+        "langage",
         "lastndays",
         "lcone",
         "lcov",
@@ -572,15 +596,19 @@
         "licenseidentifiers",
         "licensetypes",
         "lightningloginenroll",
+        "ligne",
         "linkinator",
         "liste",
         "listview",
         "listviewmine",
         "listviews",
+        "li\u00e9s",
         "localauth",
         "localconfig",
         "localecsv",
         "localfields",
+        "localisation",
+        "localisations",
         "localtest",
         "loginasgrantedtopartnerbt",
         "loglevel",
@@ -630,6 +658,7 @@
         "namespaceprefix",
         "networkidle",
         "nico",
+        "niveau",
         "noclean",
         "noconfig",
         "nodelta",
@@ -649,6 +678,7 @@
         "numberfailed",
         "nvuillam",
         "nycrc",
+        "n\u0153uds",
         "oauthcustomscope",
         "oauthcustomscopes",
         "obligatoire",
@@ -678,6 +708,7 @@
         "papaparse",
         "parseable",
         "partage",
+        "partie",
         "pascalcase",
         "passin",
         "passout",
@@ -717,7 +748,9 @@
         "profilestopermsets",
         "profiletabs",
         "projectname",
+        "projet",
         "propri\u00e9t\u00e9",
+        "pr\u00e9c\u00e9dente",
         "psga",
         "psgc",
         "psgm",
@@ -739,6 +772,7 @@
         "remotesites",
         "removedonly",
         "removepackagexml",
+        "remplacer",
         "renderable",
         "rendez",
         "reportfile",
@@ -759,10 +793,17 @@
         "ruleset",
         "runtests",
         "r\u00e9cente",
+        "r\u00e9cup\u00e9rer",
+        "r\u00e9f\u00e9rence",
+        "r\u00e9pondre",
+        "r\u00e9ponse",
+        "r\u00e9serv\u00e9",
+        "r\u00e9soudre",
         "salesforcecli",
         "salesforcedx",
         "samlssoconfig",
         "samlssoconfigs",
+        "sauter",
         "scolladon",
         "scontrols",
         "scratchorg",
@@ -812,6 +853,8 @@
         "staticresources",
         "stefanzweifel",
         "subflows",
+        "suivant",
+        "suivante",
         "superfences",
         "suspiscious",
         "sustn",
@@ -844,9 +887,11 @@
         "transco",
         "transfo",
         "transfoconfig",
+        "travaillant",
         "trivy",
         "trivyignore",
         "twemoji",
+        "t\u00eate",
         "uitype",
         "unallowed",
         "unfiled",
@@ -876,11 +921,14 @@
         "userlicense",
         "usetoolingapi",
         "utilis",
+        "utilisant",
+        "utilisateur",
         "utilisateurs",
         "utilis\u00e9",
         "uuidv",
         "validateddeployrequestid",
         "venv",
+        "veuillez",
         "viewdefinitions",
         "visualiser",
         "vous",
@@ -905,6 +953,8 @@
         "yamioliva",
         "yamllint",
         "zipfile",
+        "\u00e9l\u00e9ments",
+        "\u00eates",
         "\u00eatre",
         "\u00ecntegration"
     ]

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,15 @@
 
 Note: Can be used with `sfdx plugins:install sfdx-hardis@beta` and docker image `hardisgroupcom/sfdx-hardis@beta`
 
+## [5.15.0] 2025-01-12
+
+- Allow to call AI to describe flows in documentation
+- Allow to call AI to describe differences between 2 flow versions in a pull request comment
+- [Ai Provider](https://sfdx-hardis.cloudity.com/salesforce-ai-setup/) enhancements
+  - Change default model from gpt-4o to gpt-4o-mini
+  - Prompt templates factory, with capability to override default prompt with ENV variable
+  - Translate prompts in french
+- Add dotenv to allow to define secrets variables in a local `.env` file (never commit it !)
 - Add more ways to call python depending on the installation
 
 ## [5.14.3] 2025-01-10

diff --git a/docs/salesforce-ai-setup.md b/docs/salesforce-ai-setup.md
@@ -6,12 +6,27 @@ description: Learn how to use AI to supercharge sfdx-hardis deployments
 
 # Setup AI for sfdx-hardis
 
+## Main configuration
+
 You need to define at least env variable OPENAI_API_KEY and make it available to your CI/CD workflow.
 
-To get an OpenAi API key, [create an OpenAi Platform account](https://platform.openai.com/).
+You can contact [Cloudity](https://cloudity.com/#form) to use our fine-tuned Model for best results, or get an OpenAi API key via [OpenAi Platform](https://platform.openai.com/).
+
+| Variable                     | Description                                                                               | Default       |
+|------------------------------|-------------------------------------------------------------------------------------------|---------------|
+| OPENAI_API_KEY               | Your openai account API key                                                               |               |
+| OPENAI_MODEL                 | OpenAi model used to perform prompts (see [models list](https://openai.com/api/pricing/)) | `gpt-4o-mini` |
+| AI_MAXIMUM_CALL_NUMBER       | Maximum allowed number of calls to OpenAi API during a single sfdx-hardis command         | `10000`       |
+| PROMPTS_LANGUAGE             | Language to use for prompts results (en,fr)                                               | `en`          |
+| DEBUG_PROMPTS                | Set to true if you want prompts requests and responses in logs                            | `false`       |
+| MAX_DEPLOYMENT_TIPS_AI_CALLS | Maximum number of errors that will be analyzed by AI for a single Pull Request            | `20`          |
+
+## Templates
+
+You can override default prompts by defining the following environment variables.
 
-| Variable               | Description                                                                               | Default  |
-|------------------------|-------------------------------------------------------------------------------------------|----------|
-| OPENAI_API_KEY         | Your openai account API key                                                               |          |
-| OPENAI_MODEL           | OpenAi model used to perform prompts (see [models list](https://openai.com/api/pricing/)) | `gpt-4o` |
-| AI_MAXIMUM_CALL_NUMBER | Maximum allowed number of calls to OpenAi API during a single sfdx-hardis command         | `10`     |
+| Prompt Template               | Description                                                             |           Variables            |
+|-------------------------------|-------------------------------------------------------------------------|:------------------------------:|
+| PROMPT_SOLVE_DEPLOYMENT_ERROR | Ask AI about how to solve a deployment error                            |             ERROR              |
+| PROMPT_DESCRIBE_FLOW          | Describe a flow from its XML                                            |            FLOW_XML            |
+| PROMPT_DESCRIBE_FLOW_DIFF     | Describe the differences between 2 flow versions by comparing their XML | FLOW_XML_NEW,FLOW_XML_PREVIOUS |
diff --git a/package.json b/package.json
@@ -25,6 +25,7 @@
     "csv-stringify": "^6.5.2",
     "debug": "^4.3.6",
     "diff": "^7.0.0",
+    "dotenv": "^16.4.7",
     "email-validator": "^2.0.4",
     "exceljs": "^4.4.0",
     "extract-zip": "^2.0.1",

diff --git a/src/commands/hardis/doc/flow2markdown.ts b/src/commands/hardis/doc/flow2markdown.ts
@@ -9,14 +9,18 @@ import { WebSocketClient } from '../../../common/websocketClient.js';
 import { isCI, uxLog } from '../../../common/utils/index.js';
 import { MetadataUtils } from '../../../common/metadata-utils/index.js';
 import { generateFlowMarkdownFile, generateHistoryDiffMarkdown, generateMarkdownFileWithMermaid } from '../../../common/utils/mermaidUtils.js';
+import { CONSTANTS } from '../../../config/index.js';
 
 Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
 const messages = Messages.loadMessages('sfdx-hardis', 'org');
 
 export default class Flow2Markdown extends SfCommand<any> {
   public static title = 'Flow to Markdown';
 
-  public static description = `Generates a markdown documentation from a Flow file`;
+  public static description = `Generates a markdown documentation from a Flow file
+  
+If [AI integration](${CONSTANTS.DOC_URL_ROOT}/salesforce-ai-setup/) is configured, documentation will contain a summary of the Flow.  
+  `;
 
   public static examples = [
     '$ sf hardis:doc:flow2markdown',
@@ -75,7 +79,7 @@ export default class Flow2Markdown extends SfCommand<any> {
 
     uxLog(this, c.grey(`Generating markdown for Flow ${this.inputFile}...`));
     const flowXml = (await fs.readFile(this.inputFile, "utf8")).toString();
-    const genRes = await generateFlowMarkdownFile(this.inputFile, flowXml, this.outputFile, { collapsedDetails: false });
+    const genRes = await generateFlowMarkdownFile(this.inputFile, flowXml, this.outputFile, { collapsedDetails: false, describeWithAi: true });
     if (!genRes) {
       throw new Error("Error generating markdown file");
     }