Workflow for ZWEL messages

.github/workflows/build_test.yml

@@ -59,7 +59,7 @@ jobs:
           PR_DESCRIPTION: ${{ github.event.pull_request.body }}
         run: |
           # Safely print the PR description using Node.js
-          
+
           node -e "const fs=require('fs'); fs.writeFileSync('/tmp/pr_description.txt', process.env.PR_DESCRIPTION);"
           # Use diff to compare the two files
           if diff -wB /tmp/pr_description.txt .github/pull_request_template.md > /dev/null; then
@@ -114,13 +114,31 @@ jobs:
             echo "changelog was updated successfully."
           fi
 
+  check-messages:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: ./build
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Check defined and documented ZWEL messages
+        run: |
+          result=$(node ./buildZwelMessages.js --check)
+          if [ "${result}" != "0" ]; then
+            echo "${result}"
+            exit 1
+          fi
+
   build-test:
     runs-on: ubuntu-latest
-    needs: check-permission
-    steps: 
+    needs: [ check-permission, check-messages ]
+    steps:
       - name: '[Prep 1] Checkout'
         uses: actions/checkout@v3
-            
+
       - name: '[Dep 1] Libyaml'
         uses: actions/checkout@v3
         with:
@@ -134,7 +152,7 @@ jobs:
           repository: joenemo/quickjs-portable
           path: deps/launcher/quickjs
           ref: 'main'
-          
+
       - name: '[Dep 3] Zowe common'
         uses: actions/checkout@v3
         with:
@@ -146,14 +164,14 @@ jobs:
         uses: jfrog/setup-jfrog-cli@v2
         env:
           JF_ENV_1: ${{ secrets.JF_ARTIFACTORY_TOKEN }}
-          
+
       - name: 'convert manifest'
         run: |
           COMMIT_HASH=$(git rev-parse --verify HEAD)
           CURRENT_TIME=$(date +%s%3N)
           if [ -z ${{ github.event.pull_request.number }} ]
           then
-            CURRENT_BRANCH=${GITHUB_REF#refs/heads/} 
+            CURRENT_BRANCH=${GITHUB_REF#refs/heads/}
           else
             CURRENT_BRANCH=PR-${{ github.event.pull_request.number }}
           fi
@@ -163,10 +181,10 @@ jobs:
               -e "s|{{build\.timestamp}}|${CURRENT_TIME}|g" \
               manifest.yaml > manifest.yaml.tmp
           mv manifest.yaml.tmp manifest.yaml
-          
+
           echo "Current manifest.yaml is:"
           cat manifest.yaml
-      
+
       - name: '[Prep 3] Prepare workflow'
         uses: zowe-actions/shared-actions/prepare-workflow@main
 
@@ -190,10 +208,10 @@ jobs:
         if: ${{ success() && github.event.inputs.PERFORM_RELEASE == 'true' && env.IS_RELEASE_BRANCH == 'true' }}
         uses: zowe-actions/shared-actions/release@main
 
-      - name: '[Release 2] NPM bump version (if necessary)' 
+      - name: '[Release 2] NPM bump version (if necessary)'
         if: ${{ success() && github.event.inputs.PERFORM_RELEASE == 'true' && env.IS_RELEASE_BRANCH == 'true' }}
         uses: zowe-actions/shared-actions/bump-version@main
         with:
           version: minor
-        env: 
+        env:
           GITHUB_TOKEN: ${{ secrets.ZOWE_ROBOT_TOKEN }}

build/README.md

@@ -0,0 +1,24 @@
+# Zowe Launcher build directory
+
+## Launcher
+
+* `build.sh` - main script for building the Zowe Launcher
+* `dependencies.sh` - check and resolve the dependencies
+* `launcher.proj.env` - defines the environment variables and dependencies for building
+
+## Documentation
+
+* `zwelMessages.js` - messages definitions with reason and action
+* `buildZwelMessages.js` - node script for printing messages in MD format or check the status of defined and documented messages via `--check` flag
+
+When adding a new message:
+* Update the `zwelMessages.js` with proper text, reason and action.
+* Run `node buildZwelMessages.js` to review it
+* Run `node buildZwelMessages.js > launcher-error-codes.md` and use updated file [here](https://github.com/zowe/docs-site/blob/master/docs/troubleshoot/launcher/launcher-error-codes.md)
+
+Note: if you need a testing message, do not use `MSG_` as prefix. These messages are excluded from documentation build and check.
+
+For example:
+```c
+#define TEST1        MSG_PREFIX "9999I" "I am here\n"
+```

build/buildZwelMessages.js

@@ -0,0 +1,143 @@
+/*
+  This program and the accompanying materials are made available
+  under the terms of the Eclipse Public License v2.0 which
+  accompanies this distribution, and is available at
+  https://www.eclipse.org/legal/epl-v20.html
+
+  SPDX-License-Identifier: EPL-2.0
+
+  Copyright Contributors to the Zowe Project.
+*/
+
+import * as ZWEL from './zwelMessages.js';
+import { parseArgs } from "node:util";
+import * as fs from 'node:fs';
+
+const options = {
+    'check': { type: 'boolean', short: 'c' }
+}
+
+const { values: { check } } = parseArgs({ options });
+
+// Documentation is made in oder of Info, Error and Warning messages => IEW
+const SEVERITY_LIST = 'IEW';
+const CHAPTERS = [ 'informational', 'error', 'warning' ];
+const INTRO = `# Error Message Codes\n\nThe following error message codes may appear on Zowe Launcher SYSPRINT. Use the following message code references and the corresponding reasons and actions to help troubleshoot issues.\n`;
+const DEBUG = false;
+let sorted = [[],[],[]];
+
+// Markdown template
+const TEMPLATE = `### \${this.id}
+
+  \${this.text}
+
+  **Reason:**
+
+  \${this.reason}
+
+  **Action:**
+
+  \${this.action}
+`
+
+function resolveTemplate(templateString, data) {
+    const template = new Function('return `' + templateString + '`;');
+    return template.call(data);
+}
+
+function severityToIndex(severity) {
+    const i = SEVERITY_LIST.indexOf(severity.toUpperCase());
+    if (i === -1) {
+        throw new Error(`Wrong severity code ${severity}`);
+    }
+    return i;
+}
+
+// Basic check and sort messages by severity and in numeric code order
+function checkAndSort() {
+    ZWEL.MESSAGES.forEach(element => {
+        const severityIndex = severityToIndex(element.id.substring(element.id.length - 1));
+        const codeString = element.id.substring(4, 8);
+        if (!codeString.match(/[0-9]{4}/)) {
+            throw new Error(`Wrong numeric code for ${element.id}`);
+        }
+        const code = Number(codeString);
+        if (!element.action || !element.reason) {
+            throw new Error(`Missing action or reason for ${element.id}`);
+        }
+
+        DEBUG && console.log(`${element.id} -> ${element.text}\nR=${element.reason}\nA=${element.action}\n`);
+
+        sorted[severityIndex][code] = { id: element.id, text: element.text, reason: element.reason, action: element.action };
+    });
+}
+
+// Print as MD using the template
+function createMD() {
+    console.log(INTRO);
+    for (let svr = 0; svr < SEVERITY_LIST.length; svr ++) {
+        console.log(`## Zowe Launcher ${CHAPTERS[svr]} messages\n`);
+        sorted[svr].forEach(msg => {
+
+            DEBUG && console.log(`<!--\n${msg.id} -> ${msg.text}\nR=${msg.reason}\nA=${msg.action}\n-->`);
+
+            console.log(resolveTemplate(TEMPLATE, { id: msg.id, text: msg.text, reason: msg.reason, action: msg.action }));
+        })
+    }
+}
+
+// Check header messages and compare with ZWEL.MESSAGES
+function checkMessages(printResult) {
+    const headerFile = fs.readFileSync('../src/msg.h', 'utf8');
+    let header = [];
+    let doc = [];
+
+    headerFile.split('\n').forEach(line => {
+        if (line.match(/^#define[\ ]+MSG_[A-Z0-9_]+[\ ]+MSG_PREFIX/)) {
+            const firstApos = line.indexOf('"');
+            const secondApos = line.indexOf('"', firstApos + 1);
+            const headerCode = 'ZWEL' + line.substring(firstApos + 1, secondApos);
+            if (header.indexOf(headerCode) == -1) {
+                header.push(headerCode);
+            } else {
+                console.log(line);
+                console.log(`Message ${headerCode} already defined in header file!`);
+            }
+
+            DEBUG && console.log(`${headerCode} -> ${line}`);
+        }
+    })
+
+    ZWEL.MESSAGES.forEach(element => {
+        if (doc.indexOf(element.id) == -1) {
+            doc.push(element.id);
+        } else {
+            console.log(`Message ${element.id} already defined in documentation!`);
+        }
+    })
+
+    DEBUG && console.dir(header.sort());
+    DEBUG && console.dir(doc.sort());
+
+    let diff1 = header.filter(zwelMsg => !doc.includes(zwelMsg));
+    let diff2 = doc.filter(zwelMsg => !header.includes(zwelMsg));
+    if (printResult) {
+        console.log(diff1.length + diff2.length);
+    }
+    if (diff1.length) {
+        console.log("Missing ZWEL message(s) in documentation:");
+        console.dir(diff1);
+    }
+    if (diff2.length) {
+        console.log("Missing ZWEL message(s) in header file:");
+        console.dir(diff2);
+    }
+}
+
+if (check) {
+    checkMessages(check);
+} else {
+    checkMessages(check);
+    checkAndSort();
+    createMD();
+}