Enabled strict JSDoc usage and type highlights

.github/workflows/jira_link_to_pr.yml

@@ -5,19 +5,19 @@
 #   follow the pattern: <username>:<api token from jira>
 name: jira-description-action
 on:
-  pull_request:
-    types: [opened, reopened]
+    pull_request:
+        types: [ opened, reopened ]
 jobs:
-  add-jira-description:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: cakeinpanic/jira-description-action@v0.9.0
-        name: jira-description-action
-        with:
-          github-token: ${{ secrets.GITHUB_TOKEN }}
-          jira-token: ${{ secrets.JIRA_TOKEN }}
-          jira-base-url: https://hackolade.atlassian.net
-          skip-branches: '^(develop|main|master)$' #optional 
-          jira-project-key: 'HCK' #optional
-          use: 'both'
-          fail-when-jira-issue-not-found: false
+    add-jira-description:
+        runs-on: ubuntu-latest
+        steps:
+            -   uses: cakeinpanic/jira-description-action@v0.9.0
+                name: jira-description-action
+                with:
+                    github-token: ${{ secrets.GITHUB_TOKEN }}
+                    jira-token: ${{ secrets.JIRA_TOKEN }}
+                    jira-base-url: https://hackolade.atlassian.net
+                    skip-branches: '^(develop|main|master)$' #optional
+                    jira-project-key: 'HCK' #optional
+                    use: 'both'
+                    fail-when-jira-issue-not-found: false

.github/workflows/notif-push-to-slack.yml

@@ -1,34 +1,34 @@
 #https://docs.github.com/en/webhooks/webhook-events-and-payloads#push
 name: notify-push
 on:
-  push:
-    branches:
-        - develop
+    push:
+        branches:
+            - develop
 jobs:
-  notify:
-    runs-on: ubuntu-latest
-    env:
-        AUTHOR: ${{ github.event.pusher.name }}
-        COMMIT_PUSH_SOURCE: ${{ secrets.COMMIT_PUSH_SOURCE }}
-    steps:
-      - name: notify slack
-        id: slack
-        if: ${{ env.AUTHOR == env.COMMIT_PUSH_SOURCE }}
-        uses: slackapi/slack-github-action@v1.26.0
-        with:
-            channel-id: 'develop-direct-pushes'
-            payload: |
-                {
-                    "text": " ${{ github.event.head_commit.url }}",
-                    "blocks": [
-                    {
-                        "type": "section",
-                        "text": {
-                        "type": "mrkdwn",
-                        "text": "Push: ${{ github.event.head_commit.url }}"
-                        }
-                    }
-                    ]
-                }
+    notify:
+        runs-on: ubuntu-latest
         env:
-            SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}
+            AUTHOR: ${{ github.event.pusher.name }}
+            COMMIT_PUSH_SOURCE: ${{ secrets.COMMIT_PUSH_SOURCE }}
+        steps:
+            - name: notify slack
+              id: slack
+              if: ${{ env.AUTHOR == env.COMMIT_PUSH_SOURCE }}
+              uses: slackapi/slack-github-action@v1.26.0
+              with:
+                  channel-id: 'develop-direct-pushes'
+                  payload: |
+                      {
+                          "text": " ${{ github.event.head_commit.url }}",
+                          "blocks": [
+                          {
+                              "type": "section",
+                              "text": {
+                              "type": "mrkdwn",
+                              "text": "Push: ${{ github.event.head_commit.url }}"
+                              }
+                          }
+                          ]
+                      }
+              env:
+                  SLACK_BOT_TOKEN: ${{ secrets.SLACK_BOT_TOKEN }}

.github/workflows/trigger-pr-tests-plugins.yml

@@ -1,19 +1,19 @@
 name: Trigger PR tests (Plugins)
 
 on:
-  pull_request:
-    types: [auto_merge_enabled]
+    pull_request:
+        types: [auto_merge_enabled]
 
 jobs:
-  trigger-pr-tests-plugins:
-    name: Trigger PR tests (Plugins)
-    runs-on: ubuntu-latest
-    steps:
-      - name: Call TeamCity API endpoint
-        run: |
-          curl \
-            -X POST \
-            -H 'Authorization: Bearer ${{ secrets.TEAMCITY_TRIGGER_TESTS_TOKEN }}' \
-            -H 'Content-Type: application/json' \
-            -d '{"branchName": "pull/${{ github.event.number }}", "buildType": {"id": "${{ vars.TEAMCITY_BUILD_ID_FOR_TESTING_PLUGIN_PR }}"}}' \
-            ${{ vars.TEAMCITY_API_URL }}/buildQueue
+    trigger-pr-tests-plugins:
+        name: Trigger PR tests (Plugins)
+        runs-on: ubuntu-latest
+        steps:
+            - name: Call TeamCity API endpoint
+              run: |
+                  curl \
+                    -X POST \
+                    -H 'Authorization: Bearer ${{ secrets.TEAMCITY_TRIGGER_TESTS_TOKEN }}' \
+                    -H 'Content-Type: application/json' \
+                    -d '{"branchName": "pull/${{ github.event.number }}", "buildType": {"id": "${{ vars.TEAMCITY_BUILD_ID_FOR_TESTING_PLUGIN_PR }}"}}' \
+                    ${{ vars.TEAMCITY_API_URL }}/buildQueue

.prettierrc

@@ -8,5 +8,9 @@
 	"trailingComma": "all",
 	"bracketSpacing": true,
 	"bracketSameLine": false,
-	"arrowParens": "avoid"
+	"arrowParens": "avoid",
+	"plugins": ["prettier-plugin-jsdoc"],
+	"jsdocSeparateReturnsFromParam": false,
+	"jsdocSeparateTagGroups": false,
+	"jsdocCommentLineStrategy": "keep"
 }

eslint.config.js

@@ -3,14 +3,17 @@ const prettierPlugin = require('eslint-plugin-prettier');
 const eslintConfigPrettier = require('eslint-config-prettier');
 const importPlugin = require('eslint-plugin-import');
 const unusedImportsPlugin = require('eslint-plugin-unused-imports');
+const jsdocPlugin = require('eslint-plugin-jsdoc');
 
 /**
  * @type {import('eslint').Linter.Config[]}
  */
 module.exports = [
+	jsdocPlugin.configs['flat/recommended'],
 	{
 		plugins: {
 			'import': importPlugin,
+			'jsdoc': jsdocPlugin,
 			'unused-imports': unusedImportsPlugin,
 			'prettier': prettierPlugin,
 		},
@@ -31,6 +34,27 @@ module.exports = [
 		files: ['**/*.{js,cjs,mjs}'],
 		rules: {
 			...eslintConfigPrettier.rules,
+			'jsdoc/require-jsdoc': [
+				'error',
+				{
+					'publicOnly': false,
+					'require': {
+						'FunctionDeclaration': true,
+						'FunctionExpression': true,
+						'ArrowFunctionExpression': true,
+						'MethodDefinition': true,
+					},
+					'contexts': [
+						'FunctionDeclaration',
+						'FunctionExpression',
+						'ArrowFunctionExpression',
+						'MethodDefinition',
+					],
+				},
+			],
+			'jsdoc/tag-lines': 'off', // disabled due to conflict with prettier
+			'jsdoc/require-param-description': 'off',
+			'jsdoc/require-returns-description': 'off',
 			'no-cond-assign': 'error',
 			'no-const-assign': 'error',
 			'no-dupe-args': 'error',

forward_engineering/api.js

@@ -1,6 +1,5 @@
 /**
- * @import { ContainerLevelScriptFEData, GenerateContainerLevelScriptCallback } from "./types/types"
- * @import { Logger } from "../shared/types/types"
+ * @import {ContainerLevelScriptFEData, GenerateContainerLevelScriptCallback, ValidateScriptCallback, Logger} from "../shared/types/types"
  */
 
 const validationHelper = require('./helpers/schemaValidationHelper');
@@ -70,9 +69,9 @@ module.exports = {
 	/**
 	 * Validates the given script data.
 	 *
-	 * @param {Object} data - The data for validation.
+	 * @param {object} data - The data for validation.
 	 * @param {string} data.script - The script to be validated.
-	 * @param {Object} data.targetScriptOptions - Options for the target script.
+	 * @param {object} data.targetScriptOptions - Options for the target script.
 	 * @param {Logger} logger - The logger for logging errors.
 	 * @param {ValidateScriptCallback} cb - The callback function.
 	 */

forward_engineering/helpers/addRequiredHelper.js

@@ -1,7 +1,7 @@
 /**
  * Adds required indicator.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {string} param0.type - The type name statement.
  * @param {boolean} param0.required - Indicates if the field is required.
  * @returns {string} - The type name with required indicator.

forward_engineering/helpers/commentLinesHelper.js

@@ -1,9 +1,8 @@
 /**
- * Adds comment markers to each line of a GraphQL statement.
- * This function takes a GraphQL statement and prepends a '#' character
- * to each line, commenting out the entire statement.
+ * Adds comment markers to each line of a GraphQL statement. This function takes a GraphQL statement and prepends a '#'
+ * character to each line, commenting out the entire statement.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {string} param0.statement - The GraphQL statement to comment out
  * @returns {string} - Commented out statement
  */

forward_engineering/helpers/descriptionsHelper.js

@@ -1,8 +1,8 @@
 /**
- * Formats the description for a GraphQL statement.
- * Uses triple quotes for multi-line descriptions and single quotes for single-line descriptions.
+ * Formats the description for a GraphQL statement. Uses triple quotes for multi-line descriptions and single quotes for
+ * single-line descriptions.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {string} param0.description - The description to format
  * @returns {string} - The formatted description
  */

forward_engineering/helpers/feStatementFormatHelper.js

@@ -1,16 +1,16 @@
 /**
- * @import { FEStatement } from "../types/types"
+ * @import {FEStatement} from "../../shared/types/types";
  */
 
 const { commentLines } = require('./commentLinesHelper');
 const { getStatementDescription } = require('./descriptionsHelper');
 const { addIndentToStatement } = require('./feStatementIndentHelper');
 
 /**
- * Combines the description and statement, and comments out the statement if it is deactivated.
- * Adds formatted nested statements if they exist.
+ * Combines the description and statement, and comments out the statement if it is deactivated. Adds formatted nested
+ * statements if they exist.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {FEStatement} param0.feStatement - The forward engineering statement object.
  * @returns {string} - The final formatted statement.
  */
@@ -51,6 +51,10 @@ function formatFEStatement({ feStatement }) {
 	return result;
 }
 
+/**
+ * @param {string} [description]
+ * @returns {string}
+ */
 function formatDescription(description) {
 	if (description?.trim()) {
 		const formattedDescription = getStatementDescription({ description });
@@ -59,6 +63,10 @@ function formatDescription(description) {
 	return '';
 }
 
+/**
+ * @param {FEStatement & { isParentActivated: boolean }} params
+ * @returns {string}
+ */
 function formatNestedStatements({
 	nestedStatements,
 	isParentActivated,
@@ -113,6 +121,10 @@ function formatNestedStatements({
 	return `${formatSingleLineComment(comment)}\n${formattedNestedStatements}`;
 }
 
+/**
+ * @param {string} comment
+ * @returns {string}
+ */
 function formatSingleLineComment(comment) {
 	return comment ? ` # ${comment}` : '';
 }

forward_engineering/helpers/feStatementIndentHelper.js

@@ -3,9 +3,10 @@ const { GRAPHQL_SCHEMA_SCRIPT_INDENT } = require('../constants/feScriptConstants
 /**
  * Adds indentation to each line of a given statement.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {string} param0.statement - The statement to which indentation will be added.
- * @param {string} [param0.indent=GRAPHQL_SCHEMA_SCRIPT_INDENT] - The indentation string to use. Defaults to GRAPHQL_INDENT.
+ * @param {string} [param0.indent] - The indentation string to use. Defaults to GRAPHQL_INDENT. Default is
+ *   `GRAPHQL_SCHEMA_SCRIPT_INDENT`
  * @returns {string} - The indented statement.
  */
 function addIndentToStatement({ statement, indent = GRAPHQL_SCHEMA_SCRIPT_INDENT }) {

forward_engineering/helpers/feStatementJoinHelper.js

@@ -1,9 +1,10 @@
 /**
- * Joins an array of statements into a single line.
- * Trims each statement, filters out empty statements, and joins them with a space.
+ * Joins an array of statements into a single line. Trims each statement, filters out empty statements, and joins them
+ * with a space.
  *
- * @param {Object} param0
+ * @param {object} param0
  * @param {string[]} param0.statements - The array of statements to join.
+ * @param {string} [param0.separator]
  * @returns {string} - The joined statements as a single line.
  */
 function joinInlineStatements({ statements, separator = ' ' }) {

forward_engineering/helpers/generateIdToNameMap.js

@@ -4,8 +4,8 @@ const SYSTEM_NAMES = ['Scalars', 'Enums', 'Objects', 'Interfaces', 'Input object
 /**
  * Generate the ID to Name map for the given model definitions schema.
  *
- * @param {Object} modelDefinitionsSchema - The model definitions object properties.
- * @returns {Object} - The ID to Name map
+ * @param {object} modelDefinitionsSchema - The model definitions object properties.
+ * @returns {object} - The ID to Name map
  */
 const generateIdToNameMap = (modelDefinitionsSchema = {}) => {
 	let idToNameMap = {};

forward_engineering/helpers/referenceHelper.js

@@ -1,12 +1,13 @@
 /**
  * Get the definition name from the reference path
  *
- * @param {Object} param0
- * @param {string} [param0.referencePath] - The reference path, separated by '/', where the definition name is the last element.
+ * @param {object} param0
+ * @param {string} [param0.referencePath] - The reference path, separated by '/', where the definition name is the last
+ *   element.
  * @returns {string} - The definition name.
  */
 function getDefinitionNameFromReferencePath({ referencePath = '' }) {
-	return referencePath.split('/').pop();
+	return referencePath.split('/').pop() || '';
 }
 
 module.exports = {